@serenity-js/core 3.28.0 → 3.29.3

package/lib/screenplay/questions/Numeric.js

@@ -0,0 +1,646 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Numeric = void 0;
+const tiny_types_1 = require("tiny-types");
+const Question_1 = require("../Question");
+const tag_functions_1 = require("./tag-functions");
+/**
+ * Provides methods to perform calculations on numeric values returned by other [questions](https://serenity-js.org/api/core/class/Question/).
+ *
+ * ## Example
+ *
+ * The examples in this section demonstrate interacting with an HTML widget representing a price list.
+ *
+ * ```html
+ * <ul id="price-list">
+ *     <li class="item">
+ *         <span class="name">apples</span>
+ *         <span class="quantity">5</span>
+ *         <span class="price">£2.25</span>
+ *     </li>
+ *     <li class="item">
+ *         <span class="name">apricots</span>
+ *         <span class="quantity">4</span>
+ *         <span class="price">£3.70</span>
+ *     </li>
+ *     <li class="item">
+ *         <span class="name">bananas</span>
+ *         <span class="quantity">2</span>
+ *         <span class="price">£1.50</span>
+ *     </li>
+ * </ul>
+ * ```
+ *
+ * ### Lean Page Objects
+ *
+ * To represent our example HTML widget,
+ * we follow the [Lean Page Objects pattern](https://serenity-js.org/handbook/web-testing/page-objects-pattern/)
+ * to define the `PriceList` and `PriceListItem` classes
+ * and use the Serenity/JS [Page Element Query Language (PEQL)](https://serenity-js.org/handbook/web-testing/page-element-query-language/)
+ * to identify the elements of interest.
+ *
+ * ```ts
+ * // ui/price-list.ts
+ *
+ * import { PageElement, PageElements, By } from '@serenity-js/web'
+ *
+ * export class PriceList {
+ *   static container = () =>
+ *      PageElement.located(By.id('price-list'))
+ *          .describedAs('price list')
+ *
+ *   static items = () =>
+ *      PageElements.located(PriceListItem.containerSelector())
+ *          .of(this.container())
+ *          .describedAs('items')
+ * }
+ *
+ * export class PriceListItem {
+ *   static containerSelector = () =>
+ *     By.css('.item')
+ *
+ *   static container = () =>
+ *     PageElement.located(this.containerSelector())
+ *       .describedAs('item')
+ *
+ *   static name = () =>
+ *     PageElement.located(By.css('.name'))
+ *       .of(this.container())
+ *       .describedAs('name')
+ *
+ *   static quantity = () =>
+ *     PageElement.located(By.css('.quantity'))
+ *       .of(this.container())
+ *       .describedAs('quantity')
+ *
+ *   static price = () =>
+ *     PageElement.located(By.css('.price'))
+ *       .of(this.container())
+ *       .describedAs('price')
+ * }
+ * ```
+ *
+ * @group Questions
+ */
+class Numeric {
+    /**
+     * Returns a [`Question`](https://serenity-js.org/api/core/class/Question/) that sums up the values provided
+     * and throws if any of the values is not a `number`.
+     *
+     * #### Adding static numbers
+     *
+     * The most basic example of using the `Numeric.sum` method is to add up a few numbers.
+     *
+     * ```ts
+     * import { actorCalled, Numeric } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.sum(1, 2, 3),
+     *     equals(6),
+     *   )
+     * )
+     * ```
+     *
+     * The numbers can be provided individually, as an array, or as a combination of both.
+     *
+     * ```ts
+     * import { actorCalled, Numeric } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.sum([ 1, 2 ], 3, [ 4, 5 ]),
+     *     equals(15),
+     *   )
+     * )
+     * ```
+     *
+     * #### Adding numbers returned by other questions
+     *
+     * Apart from adding static numbers, you can also add numbers returned by other questions.
+     * This is particularly useful when you need to calculate the sum of numbers extracted from a list of UI elements
+     * or from an API response.
+     *
+     * ```ts
+     * import { actorCalled, Numeric, Question } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     * const myNumber = () =>
+     *   Question.about('my number', actor => 42)
+     *
+     * const myArrayOfNumbers = () =>
+     *   Question.about('my array of numbers', actor => [ 1, 2, 3 ])
+     *
+     * const myObjectWithNumbers = () =>
+     *   Question.about('my object with numbers', actor => ({ a: 1, b: 2, c: 3 }))
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.sum(
+     *       myNumber(),            // a question returning a number
+     *       myArrayOfNumbers(),    // a question returning an array of numbers
+     *     ),
+     *     equals(48),
+     *   ),
+     *   Ensure.that(
+     *     Numeric.sum(
+     *       myObjectWithNumbers()  // a question returning an object with numbers
+     *          .as(Object.values), // from which we extract the numeric values
+     *     ),
+     *     equals(6),
+     *   ),
+     * )
+     * ```
+     *
+     * Of course, you can also mix and match static numbers with numbers returned by questions.
+     *
+     * ```ts
+     * import { actorCalled, Numeric, Question } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     * const myObjectWithNumbers = () =>
+     *   Question.about('my object with numbers', actor => ({ a: 1, b: 2, c: 3 }))
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.sum(
+     *       myObjectWithNumbers().as(Object.values),
+     *       [ 4, 5 ],
+     *       6,
+     *     ),
+     *     equals(21),
+     *   ),
+     * )
+     * ```
+     *
+     * #### Adding numbers extracted from a UI
+     *
+     * To add numbers extracted from a UI:
+     * - use the [`PageElement`](https://serenity-js.org/api/web/class/PageElement) and [`PageElements`](https://serenity-js.org/api/web/class/PageElements) classes to identify the elements of interest,
+     * - use the [`Text.of`](https://serenity-js.org/api/web/class/Text/) or [`Text.ofAll`](https://serenity-js.org/api/web/class/Text/) questions to extract the text of the element or elements,
+     * - and then interpret this text as number using either the [`.as(Number)`](https://serenity-js.org/api/core/class/Question/#as) mapping function,
+     *   or the [`Numeric.intValue()`](https://serenity-js.org/api/core/class/Numeric/#intValue) or [`Numeric.floatValue()`](https://serenity-js.org/api/core/class/Numeric/#floatValue) meta-questions.
+     *
+     * For example, we could calculate the sum of quantities of items in our example price list by specifying each element explicitly
+     * and mapping its text to [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number):
+     *
+     * ```ts
+     * import { actorCalled, Numeric } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     * import { Text } from '@serenity-js/web'
+     * import { PriceList, PriceListItem } from './ui/price-list'
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.sum(
+     *       Text.of(PriceListItem.quantity().of(PriceList.items().first())).as(Number),
+     *       Text.of(PriceListItem.quantity().of(PriceList.items().at(1))).as(Number),
+     *       Text.of(PriceListItem.quantity().of(PriceList.items().last())).as(Number),
+     *     ),
+     *     equals(11),
+     *   ),
+     * )
+     * ```
+     *
+     * A more elegant approach would be to use the Serenity/JS [Page Element Query Language (PEQL)](https://serenity-js.org/handbook/web-testing/page-element-query-language/#mapping-page-elements-in-a-collection)
+     * to map each item in the collection to its quantity and then calculate the sum.
+     *
+     * ```ts
+     * import { actorCalled, Numeric } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     * import { Text } from '@serenity-js/web'
+     * import { PriceList, PriceListItem } from './ui/price-list'
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.sum(
+     *       PriceList.items()                      // get all the li.item elements
+     *         .eachMappedTo(
+     *           Text.of(PriceListItem.quantity())  // extract the text of the .quantity element
+     *         )
+     *         .eachMappedTo(                       // interpret the quantity as an integer value
+     *           Numeric.intValue(),
+     *         ),
+     *     ),
+     *     equals(11),                              // 5 apples, 4 apricots, 2 bananas
+     *   )
+     * )
+     * ```
+     *
+     * Using PEQL allows us to express the intent more concisely and, for example,
+     * introduce helper functions that limit the scope of the operation to a subset of elements.
+     *
+     * ```ts
+     * import { actorCalled, Expectation, Numeric, the } from '@serenity-js/core'
+     * import { Ensure, equals, startsWith } from '@serenity-js/assertions'
+     * import { PriceList, PriceListItem } from './ui/price-list'
+     *
+     * const quantitiesOfItemsWhichName = (expectation: Expectation<string>) =>
+     *   PriceList.items()                      // get all the li.item elements
+     *     .where(                              // leave only those which name matches the expectation
+     *        Text.of(PriceListItem.name()),
+     *        expectation
+     *     )
+     *     .eachMappedTo(
+     *       Text.of(PriceListItem.quantity())  // extract the text of the .quantity element
+     *     )
+     *     .eachMappedTo(                       // interpret the quantity as an integer value
+     *       Numeric.intValue(),
+     *     )
+     *     .describedAs(the`quantities of items which name does ${ expectation }`)
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.sum(
+     *       quantitiesOfItemsWhichName(startsWith('ap')),  // apples and apricots
+     *     ),
+     *     equals(9),                                       // 5 apples, 4 apricots
+     *   )
+     * )
+     * ```
+     *
+     * #### Learn more
+     *
+     * View the [`Numeric` API documentation](https://serenity-js.org/api/core/class/Numeric) for more details
+     * and examples.
+     *
+     * @param values
+     */
+    static sum(...values) {
+        return Question_1.Question.about((0, tag_functions_1.the) `the sum of ${values}`, async (actor) => {
+            const numbers = await actor.answer(this.flatten(values, (0, tiny_types_1.isNumber)()));
+            return numbers.sort()
+                .reduce((acc, current) => acc + current, 0);
+        });
+    }
+    /**
+     * Returns a [`Question`](https://serenity-js.org/api/core/class/Question/)  that calculates the difference between
+     * two numbers and throws if any of the values is not a `number`.
+     *
+     * #### Subtracting numbers
+     *
+     * ```ts
+     * import { actorCalled, Numeric } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     * import { Text } from '@serenity-js/web'
+     * import { PriceList, PriceListItem } from './ui/price-list'
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.difference(
+     *       Text.of(PriceListItem.quantity().of(PriceList.items().first())).as(Number),    // 5 (apples)
+     *       2,                                                                             // - 2
+     *     ),
+     *     equals(3),
+     *   ),
+     * )
+     * ```
+     *
+     * #### Learn more
+     *
+     * View the [`Numeric` API documentation](https://serenity-js.org/api/core/class/Numeric) for more details
+     * and examples.
+     *
+     * @param minuend
+     * @param subtrahend
+     */
+    static difference(minuend, subtrahend) {
+        return Question_1.Question.about((0, tag_functions_1.the) `the difference between ${minuend} and ${subtrahend}`, async (actor) => {
+            const minuendValue = await actor.answer(minuend);
+            const subtrahendValue = await actor.answer(subtrahend);
+            return (0, tiny_types_1.ensure)(this.descriptionOf(minuendValue), minuendValue, (0, tiny_types_1.isNumber)())
+                - (0, tiny_types_1.ensure)(this.descriptionOf(subtrahendValue), subtrahendValue, (0, tiny_types_1.isNumber)());
+        });
+    }
+    /**
+     * Returns a [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/) that calculates
+     * the ceiling of a number and throws if the value is not a `number`.
+     *
+     * #### Calculating the ceiling of a number
+     *
+     * ```ts
+     * import { actorCalled, Numeric } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     * import { Text } from '@serenity-js/web'
+     * import { PriceList, PriceListItem } from './ui/price-list'
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.ceiling().of(
+     *       Text.of(PriceListItem.price().of(PriceList.items().first()))   // '£2.25' (apples)
+     *          .replace('£', '')                                           // '2.25'
+     *          .as(Number.parseFloat),                                     // 2.25
+     *     ),
+     *     equals(3),
+     *   ),
+     * )
+     * ```
+     *
+     * #### Learn more
+     *
+     * View the [`Numeric` API documentation](https://serenity-js.org/api/core/class/Numeric) for more details
+     * and examples.
+     */
+    static ceiling() {
+        return {
+            of: (value) => Question_1.Question.about((0, tag_functions_1.the) `the ceiling of ${value}`, async (actor) => {
+                const answer = await actor.answer(value);
+                return Math.ceil((0, tiny_types_1.ensure)(this.descriptionOf(answer), answer, (0, tiny_types_1.isNumber)()));
+            }),
+        };
+    }
+    /**
+     * Returns a [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/) that calculates
+     * the floor of a number and throws if the value is not a `number`.
+     *
+     * #### Calculating the floor of a number
+     *
+     * ```ts
+     * import { actorCalled, Numeric } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     * import { Text } from '@serenity-js/web'
+     * import { PriceList, PriceListItem } from './ui/price-list'
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.floor().of(
+     *       Text.of(PriceListItem.price().of(PriceList.items().first()))   // '£2.25' (apples)
+     *          .replace('£', '')                                           // '2.25'
+     *          .as(Number.parseFloat),                                     // 2.25
+     *     ),
+     *     equals(2),
+     *   ),
+     * )
+     * ```
+     *
+     * #### Learn more
+     *
+     * View the [`Numeric` API documentation](https://serenity-js.org/api/core/class/Numeric) for more details
+     * and examples.
+     */
+    static floor() {
+        return {
+            of: (value) => Question_1.Question.about((0, tag_functions_1.the) `the floor of ${value}`, async (actor) => {
+                const answer = await actor.answer(value);
+                return Math.floor((0, tiny_types_1.ensure)(this.descriptionOf(answer), answer, (0, tiny_types_1.isNumber)()));
+            }),
+        };
+    }
+    /**
+     * Returns a [`Question`](https://serenity-js.org/api/core/class/Question/) that calculates
+     * the maximum value in the lists of numbers provided and throws if any of the values is not a `number`.
+     *
+     * #### Calculating the maximum value
+     *
+     * ```ts
+     * import { actorCalled, Numeric } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     * import { Text } from '@serenity-js/web'
+     * import { PriceList, PriceListItem } from './ui/price-list'
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.max(
+     *       PriceList.items()                      // get all the li.item elements
+     *         .eachMappedTo(
+     *           Text.of(PriceListItem.quantity())  // extract the text of the .quantity element
+     *         )
+     *         .eachMappedTo(                       // interpret the quantity as an integer value
+     *           Numeric.intValue(),
+     *         ),
+     *     ),
+     *     equals(5),                               // 5 (apples)
+     *   )
+     * )
+     * ```
+     *
+     * #### Learn more
+     *
+     * View the [`Numeric` API documentation](https://serenity-js.org/api/core/class/Numeric) for more details
+     * and examples.
+     *
+     * @param values
+     */
+    static max(...values) {
+        return Question_1.Question.about((0, tag_functions_1.the) `the max of ${values}`, async (actor) => {
+            const numbers = await actor.answer(this.flatten(values, (0, tiny_types_1.isNumber)()));
+            return numbers.sort().pop();
+        });
+    }
+    /**
+     * Returns a [`Question`](https://serenity-js.org/api/core/class/Question/) that calculates
+     * the minimum value in the lists of numbers provided and throws if any of the values is not a `number`.
+     *
+     * #### Calculating the minimum value
+     *
+     * ```ts
+     * import { actorCalled, Numeric } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     * import { Text } from '@serenity-js/web'
+     * import { PriceList, PriceListItem } from './ui/price-list'
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.min(
+     *       PriceList.items()                      // get all the li.item elements
+     *         .eachMappedTo(
+     *           Text.of(PriceListItem.quantity())  // extract the text of the .quantity element
+     *         )
+     *         .eachMappedTo(                       // interpret the quantity as an integer value
+     *           Numeric.intValue(),
+     *         ),
+     *     ),
+     *     equals(2),                               // 2 (bananas)
+     *   )
+     * )
+     * ```
+     *
+     * #### Learn more
+     *
+     * View the [`Numeric` API documentation](https://serenity-js.org/api/core/class/Numeric) for more details
+     * and examples.
+     *
+     * @param values
+     */
+    static min(...values) {
+        return Question_1.Question.about((0, tag_functions_1.the) `the min of ${values}`, async (actor) => {
+            const numbers = await actor.answer(this.flatten(values, (0, tiny_types_1.isNumber)()));
+            return numbers.sort().shift();
+        });
+    }
+    /**
+     * Returns a [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/) that parses a string `value`
+     * and returns an integer of the specified `base`.
+     * Leading whitespace in the value to parse argument is ignored.
+     *
+     * #### Parsing a string as an integer
+     *
+     * ```ts
+     * import { actorCalled, Numeric } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     * import { Text } from '@serenity-js/web'
+     * import { PriceList, PriceListItem } from './ui/price-list'
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.intValue().of(
+     *       Text.of(                           // '5' (apples)
+     *         PriceListItem.quantity().of(
+     *           PriceList.items().first()
+     *         )
+     *       )
+     *     ),
+     *     equals(5),
+     *   ),
+     * )
+     * ```
+     *
+     * #### Learn more
+     *
+     * View the [`Numeric` API documentation](https://serenity-js.org/api/core/class/Numeric) for more details
+     * and examples.
+     *
+     * @param base
+     *  An integer between 2 and 36 that represents the base in mathematical numeral systems of the string.
+     *  If base is undefined or 0, it is assumed to be 10 except when the number begins with the code unit pairs 0x or 0X, in which case a radix of 16 is assumed.
+     */
+    static intValue(base) {
+        return {
+            /**
+             * @param value
+             *  The value to parse, coerced to a string. Leading whitespace in this argument is ignored.
+             */
+            of: (value) => Question_1.Question.about((0, tag_functions_1.the) `the integer value of ${value}`, async (actor) => {
+                const description = this.descriptionOf(value);
+                const stringValue = (0, tiny_types_1.ensure)(description, await actor.answer(value), (0, tiny_types_1.isString)());
+                const maybeBase = await actor.answer(base);
+                const radix = maybeBase !== undefined && maybeBase !== null
+                    ? (0, tiny_types_1.ensure)(`base ${this.descriptionOf(base)}`, maybeBase, (0, tiny_types_1.isNumber)())
+                    : undefined;
+                const parsed = Number.parseInt(stringValue, radix);
+                if (Number.isNaN(parsed)) {
+                    throw new TypeError(`Parsing ${description} as an integer value returned a NaN`);
+                }
+                return parsed;
+            }),
+        };
+    }
+    /**
+     * Returns a [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/) that parses a string `value`
+     * and returns a [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt).
+     * Leading whitespace in the value to parse argument is ignored.
+     *
+     * #### Parsing a string as a bigint
+     *
+     * ```ts
+     * import { actorCalled, Numeric } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     * import { Text } from '@serenity-js/web'
+     * import { PriceList, PriceListItem } from './ui/price-list'
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.bigIntValue().of(
+     *       Text.of(                                                  // '5' (apples)
+     *         PriceListItem.quantity().of(PriceList.items().first())
+     *       )
+     *     ),
+     *     equals(BigInt('5')),
+     *   ),
+     * )
+     * ```
+     *
+     * #### Learn more
+     *
+     * View the [`Numeric` API documentation](https://serenity-js.org/api/core/class/Numeric) for more details
+     * and examples.
+     */
+    static bigIntValue() {
+        return {
+            /**
+             * @param value
+             *  The value to parse, coerced to a string. Leading whitespace in this argument is ignored.
+             */
+            of: (value) => Question_1.Question.about((0, tag_functions_1.the) `the bigint value of ${value}`, async (actor) => {
+                const description = this.descriptionOf(value);
+                const stringValue = (0, tiny_types_1.ensure)(description, await actor.answer(value), (0, tiny_types_1.isString)());
+                try {
+                    return BigInt(stringValue);
+                }
+                catch (error) {
+                    throw new TypeError(`Parsing ${description} as a bigint value returned an error: ${error.message || error}`);
+                }
+            }),
+        };
+    }
+    /**
+     * Returns a [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/) that parses a string `value`
+     * and returns a floating-point number.
+     *
+     * #### Parsing a string as a floating point number
+     *
+     * ```ts
+     * import { actorCalled, Numeric } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     * import { Text } from '@serenity-js/web'
+     * import { PriceList, PriceListItem } from './ui/price-list'
+     *
+     * await actorCalled('Zoé').attemptsTo(
+     *   Ensure.that(
+     *     Numeric.floatValue().of(
+     *       Text.of(                                                  // '£2.25'
+     *           PriceListItem.price().of(PriceList.items().first())
+     *       ).replace('£', '')                                        // '2.25'
+     *     ),
+     *     equals(2.25),
+     *   ),
+     * )
+     * ```
+     *
+     * #### Learn more
+     *
+     * View the [`Numeric` API documentation](https://serenity-js.org/api/core/class/Numeric) for more details
+     * and examples.
+     */
+    static floatValue() {
+        return {
+            /**
+             * @param value
+             *  The value to parse, coerced to a string. Leading whitespace in this argument is ignored.
+             */
+            of: (value) => Question_1.Question.about((0, tag_functions_1.the) `the float value of ${value}`, async (actor) => {
+                const description = this.descriptionOf(value);
+                const maybeNumber = (0, tiny_types_1.ensure)(description, await actor.answer(value), (0, tiny_types_1.isString)());
+                const parsed = Number.parseFloat(maybeNumber);
+                if (Number.isNaN(parsed)) {
+                    throw new TypeError(`Parsing ${description} as a float value returned a NaN`);
+                }
+                return parsed;
+            }),
+        };
+    }
+    static flatten(items, ...predicates) {
+        return Question_1.Question.about('flatten', async (actor) => {
+            const result = [];
+            for (const item of items) {
+                const valueOrValues = await actor.answer(item);
+                const values = Array.isArray(valueOrValues)
+                    ? valueOrValues
+                    : [valueOrValues];
+                const valuesOfCorrectType = values.map(value => (0, tiny_types_1.ensure)(this.descriptionOf(value), value, ...predicates));
+                result.push(...valuesOfCorrectType);
+            }
+            return result;
+        });
+    }
+    static descriptionOf(value) {
+        if (value === undefined) {
+            return 'undefined';
+        }
+        return Question_1.Question.formattedValue().of(value).toString();
+    }
+}
+exports.Numeric = Numeric;
+//# sourceMappingURL=Numeric.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Numeric.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Numeric.ts"],"names":[],"mappings":"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"}

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

@@ -8,6 +8,7 @@ export * from './expectations';
 export * from './List';
 export * from './Masked';
 export * from './MetaQuestion';
+export * from './Numeric';
 export * from './tag-functions';
 export * from './Unanswered';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC"}

package/lib/screenplay/questions/index.js

@@ -24,6 +24,7 @@ __exportStar(require("./expectations"), exports);
 __exportStar(require("./List"), exports);
 __exportStar(require("./Masked"), exports);
 __exportStar(require("./MetaQuestion"), exports);
+__exportStar(require("./Numeric"), exports);
 __exportStar(require("./tag-functions"), exports);
 __exportStar(require("./Unanswered"), exports);
 //# sourceMappingURL=index.js.map