@serenity-js/core 2.32.5 → 3.0.0-rc.4

package/src/screenplay/questions/Note.ts

@@ -1,3 +1,4 @@
+import { formatted } from '../../io';
 import { TakeNotes } from '../abilities';
 import { AnswersQuestions, UsesAbilities } from '../actor';
 import { Question } from '../Question';
@@ -42,6 +43,8 @@ import { Question } from '../Question';
  */
 export class Note<Answer> extends Question<Promise<Answer>> {
 
+    private subject: string;
+
     /**
      * @desc
      *  Retrieves the previously recorded answer to a given {@link Question}
@@ -58,7 +61,8 @@ export class Note<Answer> extends Question<Promise<Answer>> {
      * @param {Question<Promise<Answer>> | Question<Answer> | string} topic
      */
     constructor(private readonly topic: Question<Promise<Answer>> | Question<Answer> | string) {
-        super(`a note of ${ topic }`);
+        super();
+        this.subject = formatted `a note of ${ topic }`;
     }
 
     /**
@@ -76,4 +80,20 @@ export class Note<Answer> extends Question<Promise<Answer>> {
     answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<Answer> {
         return TakeNotes.as(actor).answerTo(this.topic);
     }
+
+    /**
+     * @desc
+     *  Changes the description of this question's subject.
+     *
+     * @param {string} subject
+     * @returns {Question<T>}
+     */
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    toString(): string {
+        return this.subject;
+    }
 }

package/src/screenplay/questions/index.ts

@@ -2,9 +2,6 @@ export * from './Check';
 export * from './Expectation';
 export * from './expectations';
 export * from './List';
-export * from './mappings';
 export * from './MetaQuestion';
 export * from './Note';
-export { Property } from './Property';
 export * from './q';
-export * from './Transform';

package/lib/io/collections/index.d.ts

@@ -1,2 +0,0 @@
-export * from './mappable';
-export * from './reducible';

package/lib/io/collections/index.js

@@ -1,15 +0,0 @@
-"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]; } });
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-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("./mappable"), exports);
-__exportStar(require("./reducible"), exports);
-//# sourceMappingURL=index.js.map

package/lib/io/collections/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/io/collections/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,6CAA2B;AAC3B,8CAA4B"}

package/lib/io/collections/mappable.d.ts

@@ -1,52 +0,0 @@
-/**
- * @desc
- *  Describes a collection providing
- *  a [`map`-like interface](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).
- *
- * @interface
- *
- * @see {@link Question#map}
- * @see {@link ElementArrayFinder}
- */
-export interface Mappable<Item> {
-    /**
-     * @desc
-     *  Applies a {@link MappingFunction} function to each element of a {@link Mappable} collection.
-     *
-     *  The callback receives an item from the collection as the first argument
-     *  and its index as the second argument.
-     *
-     * @abstract
-     *
-     * @type {function<U>(callback: (item?: Item, index?: number) => U): PromiseLike<U[]> | U[]}
-     */
-    map: <U>(callback: (item?: Item, index?: number) => U) => PromiseLike<U[]> | U[];
-}
-/**
- * @desc
- *  A mapping function converting one type into another.
- *
- * @public
- *
- * @typedef {function(item?: V, index?: number) => Promise<O> | O} Mapping<V,O>
- */
-export declare type MappingFunction<V, O> = (item?: V, index?: number) => O;
-/**
- * @desc
- *  Checks if the value is a {@link Mappable} collection of items.
- *
- * @example <caption>An Array</caption>
- *  import { Mappable } from '@serenity-js/core/lib/io';
- *
- *  Mappable.isMappable([ 1, 2, 3 ]) === true
- *
- * @example <caption>Protractor's ElementArrayFinder</caption>
- *  import { Mappable } from '@serenity-js/core/lib/io';
- *  import { element } from 'protractor';
- *
- *  Mappable.isMappable(element.all(by.tagName('li')) === true
- *
- * @param {Mappable<Item> | any} maybeCollection
- * @returns {boolean}
- */
-export declare function isMappable<Item>(maybeCollection: Mappable<Item> | any): maybeCollection is Mappable<Item>;

package/lib/io/collections/mappable.js

@@ -1,28 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isMappable = void 0;
-/**
- * @desc
- *  Checks if the value is a {@link Mappable} collection of items.
- *
- * @example <caption>An Array</caption>
- *  import { Mappable } from '@serenity-js/core/lib/io';
- *
- *  Mappable.isMappable([ 1, 2, 3 ]) === true
- *
- * @example <caption>Protractor's ElementArrayFinder</caption>
- *  import { Mappable } from '@serenity-js/core/lib/io';
- *  import { element } from 'protractor';
- *
- *  Mappable.isMappable(element.all(by.tagName('li')) === true
- *
- * @param {Mappable<Item> | any} maybeCollection
- * @returns {boolean}
- */
-function isMappable(maybeCollection) {
-    return !!maybeCollection
-        && !!maybeCollection.map
-        && typeof maybeCollection.map === 'function';
-}
-exports.isMappable = isMappable;
-//# sourceMappingURL=mappable.js.map

package/lib/io/collections/mappable.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"mappable.js","sourceRoot":"","sources":["../../../src/io/collections/mappable.ts"],"names":[],"mappings":";;;AAqCA;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,UAAU,CAAO,eAAqC;IAClE,OAAO,CAAC,CAAE,eAAe;WAClB,CAAC,CAAE,eAAe,CAAC,GAAG;WACtB,OAAO,eAAe,CAAC,GAAG,KAAK,UAAU,CAAC;AACrD,CAAC;AAJD,gCAIC"}

package/lib/io/collections/reducible.d.ts

@@ -1,16 +0,0 @@
-/**
- * @desc
- *  Describes a collection providing
- *  a [`reduce`-like interface](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce).
- *
- * @interface
- *
- * @see {@link ElementArrayFinder}
- * @see {@link Loop}
- */
-export interface Reducible {
-    /**
-     * @type {function<T,A>(callback: (accumulator: A, currentValue: T, index: number) => A, initialValue: A): PromiseLike<A> | A}
-     */
-    reduce: <T, A>(fn: (accumulator: A, currentValue: T, index: number) => A, initialValue: A) => PromiseLike<A> | A;
-}

package/lib/io/collections/reducible.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"reducible.js","sourceRoot":"","sources":["../../../src/io/collections/reducible.ts"],"names":[],"mappings":""}

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

@@ -1,91 +0,0 @@
-import { Answerable } from '../Answerable';
-import { WithPropertiesAsMetaQuestions, WithPropertiesAsQuestions } from './proxies';
-/**
- * @desc
- *  Enables easy access to properties of the value of a given {@link Answerable}.
- *
- * @example <caption>Example API response</caption>
- *  interface EnvironmentDetails {
- *      name: string;
- *      url:  string;
- *  }
- *
- *  interface EnvironmentsResponse {
- *      environments: EnvironmentDetails[];
- *  }
- *
- *  const response: EnvironmentsResponse = {
- *     "environments": [
- *         {
- *             "name": "dev",
- *             "url":  "https://dev.example.com"
- *         },
- *         {
- *             "name": "sit",
- *             "url":  "https://sit.example.com"
- *         }
- *     ]
- *  }
- *
- * @example <caption>Combining Property.of and Property.at</caption>
- *  import { actorCalled, List, Property } from '@serenity-js/core';
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *
- *  actorCalled('Lisa').attemptsTo(
- *      Ensure.that(
- *          Property.of(
- *              List.of(response.environments)
- *                  .where(Property.at<EnvironmentDetails>().name, equals('dev'))
- *                  .first(),
- *          ).url,
- *          equals('https://dev.example.com')
- *      )
- *  )
- *
- * @see {@link Question}
- * @see {@link List}
- */
-export declare class Property {
-    /**
-     * @desc
-     *  Generates a {@link Proxy} around a given {@link Answerable} `subject`
-     *  to turn the properties of the value it will resolve to into {@link Question}s.
-     *
-     * @example <caption>Reading a property</caption>
-     *  import { actorCalled, Property } from '@serenity-js/core';
-     *  import { Ensure, equals } from '@serenity-js/assertions';
-     *
-     *  actorCalled('Lisa').attemptsTo(
-     *      Ensure.that(
-     *          Property.of(response).environments[0].name,
-     *          equals('dev')
-     *      )
-     *  )
-     *
-     * @param {Answerable<Subject>} subject
-     * @returns {Proxy<Subject>}
-     */
-    static of<Subject extends object>(subject: Answerable<Subject>): WithPropertiesAsQuestions<Subject>;
-    /**
-     * @desc
-     *  Generates a {@link Proxy} around a given {@link Answerable} `subject`
-     *  to turn any of its properties into {@link MetaQuestion}s
-     *  to be used when filtering a {@link List},
-     *
-     * @example <caption>Reading a property</caption>
-     *  import { actorCalled, Property } from '@serenity-js/core';
-     *  import { Ensure, equals } from '@serenity-js/assertions';
-     *
-     *  actorCalled('Lisa').attemptsTo(
-     *      Ensure.that(
-     *          List.of(response.environments)
-     *              .where(Property.at<EnvironmentDetails>().name, equals('dev'))
-     *              .first(),
-     *          equals(response.environments[0])
-     *      )
-     *  )
-     *
-     * @returns {Proxy<Subject>}
-     */
-    static at<Subject extends object>(): WithPropertiesAsMetaQuestions<Subject>;
-}

package/lib/screenplay/questions/Property.js

@@ -1,99 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Property = void 0;
-const proxies_1 = require("./proxies");
-/**
- * @desc
- *  Enables easy access to properties of the value of a given {@link Answerable}.
- *
- * @example <caption>Example API response</caption>
- *  interface EnvironmentDetails {
- *      name: string;
- *      url:  string;
- *  }
- *
- *  interface EnvironmentsResponse {
- *      environments: EnvironmentDetails[];
- *  }
- *
- *  const response: EnvironmentsResponse = {
- *     "environments": [
- *         {
- *             "name": "dev",
- *             "url":  "https://dev.example.com"
- *         },
- *         {
- *             "name": "sit",
- *             "url":  "https://sit.example.com"
- *         }
- *     ]
- *  }
- *
- * @example <caption>Combining Property.of and Property.at</caption>
- *  import { actorCalled, List, Property } from '@serenity-js/core';
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *
- *  actorCalled('Lisa').attemptsTo(
- *      Ensure.that(
- *          Property.of(
- *              List.of(response.environments)
- *                  .where(Property.at<EnvironmentDetails>().name, equals('dev'))
- *                  .first(),
- *          ).url,
- *          equals('https://dev.example.com')
- *      )
- *  )
- *
- * @see {@link Question}
- * @see {@link List}
- */
-class Property {
-    /**
-     * @desc
-     *  Generates a {@link Proxy} around a given {@link Answerable} `subject`
-     *  to turn the properties of the value it will resolve to into {@link Question}s.
-     *
-     * @example <caption>Reading a property</caption>
-     *  import { actorCalled, Property } from '@serenity-js/core';
-     *  import { Ensure, equals } from '@serenity-js/assertions';
-     *
-     *  actorCalled('Lisa').attemptsTo(
-     *      Ensure.that(
-     *          Property.of(response).environments[0].name,
-     *          equals('dev')
-     *      )
-     *  )
-     *
-     * @param {Answerable<Subject>} subject
-     * @returns {Proxy<Subject>}
-     */
-    static of(subject) {
-        return (0, proxies_1.createQuestionProxy)(subject);
-    }
-    /**
-     * @desc
-     *  Generates a {@link Proxy} around a given {@link Answerable} `subject`
-     *  to turn any of its properties into {@link MetaQuestion}s
-     *  to be used when filtering a {@link List},
-     *
-     * @example <caption>Reading a property</caption>
-     *  import { actorCalled, Property } from '@serenity-js/core';
-     *  import { Ensure, equals } from '@serenity-js/assertions';
-     *
-     *  actorCalled('Lisa').attemptsTo(
-     *      Ensure.that(
-     *          List.of(response.environments)
-     *              .where(Property.at<EnvironmentDetails>().name, equals('dev'))
-     *              .first(),
-     *          equals(response.environments[0])
-     *      )
-     *  )
-     *
-     * @returns {Proxy<Subject>}
-     */
-    static at() {
-        return (0, proxies_1.createMetaQuestionProxy)();
-    }
-}
-exports.Property = Property;
-//# sourceMappingURL=Property.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"Property.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Property.ts"],"names":[],"mappings":";;;AACA,uCAAmI;AAEnI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAa,QAAQ;IAEjB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,EAAE,CAAyB,OAA4B;QAC1D,OAAO,IAAA,6BAAmB,EAAU,OAAO,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,EAAE;QACL,OAAO,IAAA,iCAAuB,GAAW,CAAC;IAC9C,CAAC;CACJ;AAjDD,4BAiDC"}

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

@@ -1,31 +0,0 @@
-import { AnswersQuestions, UsesAbilities } from '../actor';
-import { Answerable } from '../Answerable';
-import { Question } from '../Question';
-/**
- * @experimental
- */
-export declare class Transform<Answer_Type extends any, Output_Type> extends Question<Promise<Output_Type>> {
-    private readonly questions;
-    private readonly transformation;
-    private readonly description;
-    static the<AT extends any, OT>(questions: Answerable<AT> | Array<Answerable<AT>>, transformation: (...answers: AT[]) => OT): Transform<AT, OT>;
-    constructor(questions: Array<Answerable<Answer_Type>>, transformation: (...answers: Answer_Type[]) => Output_Type, description?: string);
-    /**
-     * @deprecated
-     *  Please use {@link Transform#describedAs} instead
-     *
-     * @desc
-     *  Overrides the default {@link Transform#toString} representation of this object.
-     *
-     * @param {string} description
-     * @returns {Transform<Answer_Type, Output_Type>}
-     */
-    as(description: string): Transform<Answer_Type, Output_Type>;
-    /**
-     * Changes the description of this question's subject.
-     *
-     * @param subject
-     */
-    describedAs(subject: string): this;
-    answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<Output_Type>;
-}

package/lib/screenplay/questions/Transform.js

@@ -1,46 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Transform = void 0;
-const Question_1 = require("../Question");
-/**
- * @experimental
- */
-class Transform extends Question_1.Question {
-    constructor(questions, transformation, description = `a transformed answer`) {
-        super(description);
-        this.questions = questions;
-        this.transformation = transformation;
-        this.description = description;
-    }
-    static the(questions, transformation) {
-        return new Transform([].concat(questions), transformation);
-    }
-    /**
-     * @deprecated
-     *  Please use {@link Transform#describedAs} instead
-     *
-     * @desc
-     *  Overrides the default {@link Transform#toString} representation of this object.
-     *
-     * @param {string} description
-     * @returns {Transform<Answer_Type, Output_Type>}
-     */
-    as(description) {
-        return this.describedAs(description);
-    }
-    /**
-     * Changes the description of this question's subject.
-     *
-     * @param subject
-     */
-    describedAs(subject) {
-        this.subject = subject;
-        return this;
-    }
-    answeredBy(actor) {
-        return Promise.all(this.questions.map(question => actor.answer(question)))
-            .then(answers => this.transformation(...answers));
-    }
-}
-exports.Transform = Transform;
-//# sourceMappingURL=Transform.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"Transform.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Transform.ts"],"names":[],"mappings":";;;AAGA,0CAAuC;AAEvC;;GAEG;AACH,MAAa,SAAgD,SAAQ,mBAA8B;IAK/F,YACqB,SAAyC,EACzC,cAA0D,EAC1D,cAAsB,sBAAsB;QAE7D,KAAK,CAAC,WAAW,CAAC,CAAC;QAJF,cAAS,GAAT,SAAS,CAAgC;QACzC,mBAAc,GAAd,cAAc,CAA4C;QAC1D,gBAAW,GAAX,WAAW,CAAiC;IAGjE,CAAC;IAVD,MAAM,CAAC,GAAG,CAAqB,SAAiD,EAAE,cAAwC;QACtH,OAAO,IAAI,SAAS,CAAS,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC,CAAC;IACvE,CAAC;IAUD;;;;;;;;;OASG;IACH,EAAE,CAAC,WAAmB;QAClB,OAAO,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACH,WAAW,CAAC,OAAe;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAEvB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,UAAU,CAAC,KAAuC;QAC9C,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;aACrE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAC1D,CAAC;CACJ;AA1CD,8BA0CC"}

package/lib/screenplay/questions/lists/ArrayListAdapter.d.ts

@@ -1,88 +0,0 @@
-import { AnswersQuestions, UsesAbilities } from '../../actor';
-import { Answerable } from '../../Answerable';
-import { Expectation } from '../Expectation';
-import { MetaQuestion } from '../MetaQuestion';
-import { ListAdapter } from './ListAdapter';
-/**
- * @desc
- *  Adapts an {@link Array} so that it can be used with {@link List}
- *
- * @implements {ListAdapter}
- */
-export declare class ArrayListAdapter<Item_Type> implements ListAdapter<Item_Type, Item_Type[], Promise<Item_Type>, Promise<Item_Type[]>> {
-    private readonly array;
-    /**
-     * @param {Answerable<Item_Type[]>} array
-     */
-    constructor(array: Answerable<Item_Type[]>);
-    /**
-     * @desc
-     *  Returns the number of items the underlying {@link Array} contains,
-     *  left after applying any filters.
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {Promise<number>}
-     */
-    count(actor: AnswersQuestions & UsesAbilities): Promise<number>;
-    /**
-     * @desc
-     *  Returns the underlying {@link Array},
-     *  with any filters applied.
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {Promise<number>}
-     */
-    items(actor: AnswersQuestions & UsesAbilities): Promise<Item_Type[]>;
-    /**
-     * @desc
-     *  Returns the first of items the underlying {@link Array} contains,
-     *  left after applying any filters.
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {Promise<Item_Type>}
-     */
-    first(actor: AnswersQuestions & UsesAbilities): Promise<Item_Type>;
-    /**
-     * @desc
-     *  Returns the nth of items the underlying {@link Array} contains,
-     *  left after applying any filters.
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     *
-     * @param {number} index
-     *  Zero-based index of the item to return
-     *
-     * @returns {Promise<Item_Type>}
-     */
-    get(actor: AnswersQuestions & UsesAbilities, index: number): Promise<Item_Type>;
-    /**
-     * @desc
-     *  Returns the last of items the underlying {@link Array} contains,
-     *  left after applying any filters.
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {Promise<Item_Type>}
-     */
-    last(actor: AnswersQuestions & UsesAbilities): Promise<Item_Type>;
-    /**
-     * @desc
-     *  Filters the underlying {@link Array} so that the result contains only those items that meet the {@link Expectation}
-     *
-     * @param {MetaQuestion<Item_Type, Promise<Answer_Type> | Answer_Type>} question
-     * @param {Expectation<any, Answer_Type>} expectation
-     *
-     * @returns {ListAdapter<Item_Type, Item_Type[], Promise<Item_Type>, Promise<Item_Type[]>>}
-     *
-     * @see {MetaQuestion}
-     */
-    withFilter<Answer_Type>(question: MetaQuestion<Item_Type, Promise<Answer_Type> | Answer_Type>, expectation: Expectation<any, Answer_Type>): ListAdapter<Item_Type, Item_Type[], Promise<Item_Type>, Promise<Item_Type[]>>;
-    /**
-     * @desc
-     *  Returns a human-readable description of the underlying {@link Array}.
-     *
-     * @returns {string}
-     */
-    toString(): string;
-    private arrayAs;
-    private getItemAt;
-}