@serenity-js/core 2.33.1 → 3.0.0-rc.11

package/src/screenplay/questions/List.ts

@@ -1,260 +1,251 @@
-import { formatted } from '../../io';
-import { AnswersQuestions, UsesAbilities } from '../actor';
+import { LogicError } from '../../errors';
+import { d } from '../../io';
+import { Actor, AnswersQuestions, UsesAbilities } from '../actor';
 import { Answerable } from '../Answerable';
-import { Question } from '../Question';
+import { Question, QuestionAdapter } from '../Question';
+import { Task } from '../Task';
 import { Expectation } from './Expectation';
-import { ArrayListAdapter, ListAdapter } from './lists';
+import { ExpectationMet } from './expectations';
 import { MetaQuestion } from './MetaQuestion';
 
+export class List<Item_Type> extends Question<Promise<Item_Type[]>> {
+    private subject: string;
+
+    static of<IT>(collection: Answerable<Array<IT>>): List<IT> {
+        return new List<IT>(collection);
+    }
+
+    constructor(
+        protected readonly collection: Answerable<Array<Item_Type>>,
+    ) {
+        super();
+        this.subject = d`${ collection }`;
+    }
+
+    eachMappedTo<Mapped_Item_Type>(
+        question: MetaQuestion<Item_Type, Promise<Mapped_Item_Type> | Mapped_Item_Type>,
+    ): List<Mapped_Item_Type> {
+        return new List(
+            new EachMappedTo(this.collection, question, this.subject)
+        );
+    }
+
+    forEach(callback: (current: CurrentItem<Item_Type>, index: number, items: Array<Item_Type>) => Promise<void> | void): Task {
+        return new ForEachLoop(this.collection, this.subject, callback);
+    }
+
+    where<Answer_Type>(
+        question: MetaQuestion<Item_Type, Promise<Answer_Type> | Answer_Type>,
+        expectation: Expectation<Answer_Type>
+    ): this {
+        return new List<Item_Type>(
+            new Where(this.collection, question, expectation, this.subject)
+        ) as this;
+    }
+
+    count(): QuestionAdapter<number> {
+        return Question.about(`the number of ${ this.subject }`, async actor => {
+            const items = await this.answeredBy(actor);
+            return items.length;
+        });
+    }
+
+    first(): QuestionAdapter<Item_Type> {
+        return Question.about(`the first of ${ this.subject }`, async actor => {
+            const items = await this.answeredBy(actor);
+
+            if (items.length === 0) {
+                throw new LogicError(d`Can't retrieve the first item from a list with 0 items: ${ items }`)
+            }
+
+            return items[0];
+        });
+    }
+
+    last(): QuestionAdapter<Item_Type> {
+        return Question.about(`the last of ${ this.subject }`, async actor => {
+            const items = await this.answeredBy(actor);
+
+            if (items.length === 0) {
+                throw new LogicError(d`Can't retrieve the last item from a list with 0 items: ${ items }`)
+            }
+
+            return items[items.length - 1];
+        });
+    }
+
+    get(index: number): QuestionAdapter<Item_Type> {
+        return Question.about(`the ${ ordinal(index + 1) } of ${ this.subject }`, async actor => {
+            const items = await this.answeredBy(actor);
+
+            if (index < 0 || items.length <= index) {
+                throw new LogicError(`Can't retrieve the ${ ordinal(index) } item from a list with ${ items.length } items: ` + d`${ items }`)
+            }
+
+            return items[index];
+        });
+    }
+
+    async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<Array<Item_Type>> {
+        const collection = await actor.answer(this.collection);
+
+        if (! Array.isArray(collection)) {
+            throw new LogicError(d`A List has to wrap an Array-compatible object. ${ collection } given.`);
+        }
+
+        return collection;
+    }
+
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    toString(): string {
+        return this.subject;
+    }
+}
+
 /**
- * @desc
- *  Filters an {@link Answerable} list of items based on the criteria provided.
- *  Instantiate via {@link List.of}
- *
- * @example <caption>Example data structure</caption>
- *  interface TestAccount {
- *      username: string;
- *      role: string;
- *      environments: string[];
- *  }
- *
- *  const testAccounts: TestAccount[] = [
- *      {
- *          "username": "tester.one@example.com",
- *          "role": "test-automation"
- *          "environments": [ "dev", "sit" ],
- *      },
- *      {
- *          "username": "tester.two@example.com",
- *          "role": "test-automation"
- *          "environments": [ "dev", "sit", "prod" ],
- *      },
- *      {
- *          "username": "release.bot@example.com",
- *          "role": "release-automation"
- *          "environments": [ "dev", "sit", "prod" ],
- *      }
- *  ]
- *
- * @example <caption>Using with Property</caption>
- *  import { actorCalled, List, Property } from '@serenity-js/core';
- *  import { contain, Ensure, equals } from '@serenity-js/assertions';
- *
- *  actorCalled('Lisa').attemptsTo(
- *      Ensure.that(
- *          Property.of(
- *              List.of(testAccounts)
- *                  .where(Property.at<TestAccount>().environments, contain('prod'))
- *                  .where(Property.at<TestAccount>().role, equals('test-automation'))
- *                  .first()
- *              ).username,
- *          equals('tester.two@example.com')
- *      )
- *  )
- *
- * @extends {Question}
- * @see {@link MetaQuestion}
+ * @package
+ * @param {number} index
  */
-export class List<
-    List_Adapter_Type extends ListAdapter<Item_Type, Collection_Type, Item_Return_Type, Collection_Return_Type>,
-    Item_Type,
-    Collection_Type,
-    Item_Return_Type = Item_Type,
-    Collection_Return_Type = Collection_Type,
->
-    extends Question<Collection_Return_Type>
+function ordinal(index: number): string {
+    const
+        lastDigit     = Math.abs(index) % 10,
+        lastTwoDigits = Math.abs(index) % 100;
+
+    switch (true) {
+        case (lastDigit === 1 && lastTwoDigits !== 11):
+            return index + 'st';
+        case (lastDigit === 2 && lastTwoDigits !== 12):
+            return index + 'nd';
+        case (lastDigit === 3 && lastTwoDigits !== 13):
+            return index + 'rd';
+        default:
+            return index + 'th';
+    }
+}
+
+/**
+ * @package
+ */
+class Where<Item_Type, Answer_Type>
+    extends Question<Promise<Array<Item_Type>>>
 {
+    private subject: string;
 
-    /**
-     * @desc
-     *  Instantiates a new {@link List} configured to support standard {@link Array}.
-     *
-     *  **Please note:** Don't use `List.of` to wrap `Question<ElementArrayFinder>` returned by
-     *  [`Target.all`](/modules/protractor/class/src/screenplay/questions/targets/Target.ts~Target.html#static-method-all).
-     *  Instead, use [`Target.all(...).located(...).where(...)`](/modules/protractor/class/src/screenplay/questions/targets/Target.ts~Target.html),
-     *  which uses a Protractor-specific {@link ListAdapter}.
-     *
-     * @param {Answerable<Item_Type[]>} items
-     *
-     * @returns {List<ArrayListAdapter<Item_Type>, Item_Type, Item_Type[], Promise<Item_Type>, Promise<Item_Type[]>>}
-     */
-    static of<Item_Type>(items: Answerable<Item_Type[]>): List<ArrayListAdapter<Item_Type>, Item_Type, Item_Type[], Promise<Item_Type>, Promise<Item_Type[]>> {
-        return new List<ArrayListAdapter<Item_Type>, Item_Type, Item_Type[], Promise<Item_Type>, Promise<Item_Type[]>>(
-            new ArrayListAdapter(items)
-        );
+    constructor(
+        private readonly collection: Answerable<Array<Item_Type>>,
+        private readonly question: MetaQuestion<Item_Type, Promise<Answer_Type> | Answer_Type>,
+        private readonly expectation: Expectation<Answer_Type>,
+        originalSubject: string,
+    ) {
+        super();
+
+        const prefix = this.collection instanceof Where
+            ? ' and'
+            : ' where';
+
+        this.subject = originalSubject + prefix + d` ${ question } does ${ expectation }`;
     }
 
-    /**
-     * @param {List_Adapter_Type} collection
-     */
-    constructor(private readonly collection: List_Adapter_Type) {
-        super(formatted`${ collection }`);
+    async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<Array<Item_Type>> {
+        try {
+            const collection    = await actor.answer(this.collection);
+            const results: Item_Type[] = [];
+
+            for (const item of collection) {
+                const actual = this.question.of(item) as Answerable<Answer_Type>;
+                const expectationOutcome = await actor.answer(this.expectation.isMetFor(actual));
+
+                if (expectationOutcome instanceof ExpectationMet) {
+                    results.push(item);
+                }
+            }
+
+            return results;
+        } catch (error) {
+            throw new LogicError(d`Couldn't check if ${ this.question } of an item of ${ this.collection } does ${ this.expectation }`, error);
+        }
     }
 
-    /**
-     * @desc
-     *  Returns the number of items left after applying any filters,
-     *
-     * @example <caption>Counting items</caption>
-     *  import { actorCalled, List } from '@serenity-js/core';
-     *  import { Ensure, equals, property } from '@serenity-js/assertions';
-     *
-     *  actorCalled('Lisa').attemptsTo(
-     *      Ensure.that(
-     *          List.of(testAccounts).count(),
-     *          equals(3)
-     *      )
-     *  )
-     *
-     * @returns {Question<Promise<number>>}
-     *
-     * @see {@link List#where}
-     */
-    count(): Question<Promise<number>> {
-        return Question.about(`the number of ${ this.collection.toString() }`, actor =>
-            this.collection.count(actor)
-        );
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
     }
 
-    /**
-     * @desc
-     *  Returns the first of items left after applying any filters,
-     *
-     * @example <caption>Retrieving the first item</caption>
-     *  import { actorCalled, List } from '@serenity-js/core';
-     *  import { Ensure, equals, property } from '@serenity-js/assertions';
-     *
-     *  actorCalled('Lisa').attemptsTo(
-     *      Ensure.that(
-     *          List.of(testAccounts).first(),
-     *          property('username', equals('tester.one@example.com'))
-     *      )
-     *  )
-     *
-     * @returns {Question<Item_Return_Type>}
-     *
-     * @see {@link List#where}
-     */
-    first(): Question<Item_Return_Type> {
-        return Question.about(`the first of ${ this.collection.toString() }`, actor =>
-            this.collection.first(actor)
-        );
+    toString(): string {
+        return this.subject;
     }
+}
 
-    /**
-     * @desc
-     *  Returns the last of items left after applying any filters,
-     *
-     * @example <caption>Retrieving the last item</caption>
-     *  import { actorCalled, List } from '@serenity-js/core';
-     *  import { Ensure, equals, property } from '@serenity-js/assertions';
-     *
-     *  actorCalled('Lisa').attemptsTo(
-     *      Ensure.that(
-     *          List.of(testAccounts).last(),
-     *          property('username', equals('release.bot@example.com'))
-     *      )
-     *  )
-     *
-     * @returns {Question<Item_Return_Type>}
-     *
-     * @see {@link List#where}
-     */
-    last(): Question<Item_Return_Type> {
-        return Question.about(`the last of ${ this.collection.toString() }`, actor =>
-            this.collection.last(actor)
-        );
+/**
+ * @package
+ */
+class EachMappedTo<Item_Type, Mapped_Item_Type> extends Question<Promise<Array<Mapped_Item_Type>>> {
+
+    private subject: string;
+
+    constructor(
+        private readonly collection: Answerable<Array<Item_Type>>,
+        private readonly mapping: MetaQuestion<Item_Type, Promise<Mapped_Item_Type> | Mapped_Item_Type>,
+        originalSubject: string,
+    ) {
+        super();
+
+        this.subject = originalSubject + d` mapped to ${ this.mapping }`;
     }
 
-    /**
-     * @desc
-     *  Returns the nth of the items left after applying any filters,
-     *
-     * @example <caption>Retrieving the nth item</caption>
-     *  import { actorCalled, List } from '@serenity-js/core';
-     *  import { Ensure, equals, property } from '@serenity-js/assertions';
-     *
-     *  actorCalled('Lisa').attemptsTo(
-     *      Ensure.that(
-     *          List.of(testAccounts).get(1),
-     *          property('username', equals('tester.two@example.com'))
-     *      )
-     *  )
-     *
-     * @param {number} index
-     *  Zero-based index of the item to return
-     *
-     * @returns {Question<Item_Return_Type>}
-     *
-     * @see {@link List#where}
-     */
-    get(index: number): Question<Item_Return_Type> {
-        return Question.about(`the ${ List.ordinalSuffixOf(index + 1) } of ${ this.collection }`, actor =>
-            this.collection.get(actor, index)
-        );
+    async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<Array<Mapped_Item_Type>> {
+        const collection: Array<Item_Type> = await actor.answer(this.collection);
+
+        const mapped: Mapped_Item_Type[] = [];
+
+        for (const item of collection) {
+            mapped.push(await actor.answer(this.mapping.of(item)))
+        }
+
+        return mapped;
     }
 
-    /**
-     * @desc
-     *  Filters the underlying collection so that the result contains only those elements that meet the {@link Expectation}
-     *
-     * @example <caption>Filtering a list</caption>
-     *  import { actorCalled, List, Property } from '@serenity-js/core';
-     *  import { contain, Ensure, equals, property } from '@serenity-js/assertions';
-     *
-     *  actorCalled('Lisa').attemptsTo(
-     *      Ensure.that(
-     *          List.of(testAccounts)
-     *              .where(Property.at<TestAccount>().environments, contain('prod'))
-     *              .where(Property.at<TestAccount>().role, equals('test-automation'))
-     *              .first(),
-     *          property('username', equals('tester.two@example.com'))
-     *      )
-     *  )
-     *
-     * @param {MetaQuestion<Item_Type, Promise<Answer_Type> | Answer_Type>} question
-     * @param {Expectation<any, Answer_Type>} expectation
-     *
-     * @returns {List<List_Adapter_Type, Item_Type, Collection_Type, Item_Return_Type, Collection_Return_Type>}
-     */
-    where<Answer_Type>(
-        question: MetaQuestion<Item_Type, Promise<Answer_Type> | Answer_Type>,
-        expectation: Expectation<any, Answer_Type>,
-    ): List<List_Adapter_Type, Item_Type, Collection_Type, Item_Return_Type, Collection_Return_Type> {
-        return new List<List_Adapter_Type, Item_Type, Collection_Type, Item_Return_Type, Collection_Return_Type>(
-            this.collection.withFilter(question, expectation) as List_Adapter_Type,
-        );
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
     }
 
-    /**
-     * @desc
-     *  Makes the provided {@link Actor} answer this {@link Question} and return the underlying collection.
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {Collection_Return_Type}
-     *
-     * @see {@link Actor}
-     * @see {@link AnswersQuestions}
-     * @see {@link UsesAbilities}
-     */
-    answeredBy(actor: AnswersQuestions & UsesAbilities): Collection_Return_Type {
-        return this.collection.items(actor);
+    toString(): string {
+        return this.subject;
     }
+}
 
-    private static ordinalSuffixOf(index: number): string {
-        const
-            lastDigit = index % 10,
-            lastTwoDigits = index % 100;
-
-        switch (true) {
-            case (lastDigit === 1 && lastTwoDigits !== 11):
-                return index + 'st';
-            case (lastDigit === 2 && lastTwoDigits !== 12):
-                return index + 'nd';
-            case (lastDigit === 3 && lastTwoDigits !== 13):
-                return index + 'rd';
-            default:
-                return index + 'th';
+/**
+ * @package
+ */
+class ForEachLoop<Item_Type> extends Task {
+
+    constructor(
+        private readonly collection: Answerable<Array<Item_Type>>,
+        private readonly subject: string,
+        private readonly fn: (current: CurrentItem<Item_Type>, index: number, items: Array<Item_Type>) => Promise<void> | void,
+    ) {
+        super();
+    }
+
+    async performAs(actor: Actor): Promise<void> {
+        const collection: Array<Item_Type> = await actor.answer(this.collection);
+
+        for (const [index, item] of collection.entries()) {
+            await this.fn({ actor, item }, index, collection);
         }
     }
+
+    toString(): string {
+        return `#actor iterates over ${ this.subject }`;
+    }
+}
+
+export interface CurrentItem<Item_Type> {
+    item: Item_Type;
+    actor: Actor;
 }

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/src/stage/index.ts

@@ -1,11 +1,9 @@
 export * from './Cast';
 export * from './Clock';
 export * from './crew';
-export * from './DressingRoom';
 export * from './ListensToDomainEvents';
 export * from './Stage';
 export * from './StageCrewMember';
 export * from './StageCrewMemberBuilder';
 export * from './StageCrewMemberBuilderDependencies';
 export * from './StageManager';
-export * from './WithStage';

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"}