@serenity-js/core 3.41.1 → 3.42.0

package/esm/screenplay/time/models/Timestamp.js

@@ -0,0 +1,113 @@
+import { inspect } from 'node:util';
+import { ensure, isDefined, isInstanceOf, Predicate, TinyType } from 'tiny-types';
+import { Duration } from './Duration.js';
+/**
+ * Represents a point in time.
+ *
+ * `Timestamp` makes it easier for you to work with information related to time, like [Serenity/JS domain events](https://serenity-js.org/api/core-events/class/DomainEvent/).
+ *
+ * ## Learn more
+ * - [`Duration`](https://serenity-js.org/api/core/class/Duration/)
+ * - [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
+ *
+ * @group Time
+ */
+export class Timestamp extends TinyType {
+    value;
+    static fromJSON(v) {
+        return new Timestamp(new Date(ensure(Timestamp.name, v, isSerialisedISO8601Date())));
+    }
+    static fromTimestampInSeconds(value) {
+        return Timestamp.fromTimestampInMilliseconds(value * 1000);
+    }
+    static fromTimestampInMilliseconds(value) {
+        return new Timestamp(new Date(value));
+    }
+    static now() {
+        return new Timestamp();
+    }
+    constructor(value = new Date()) {
+        super();
+        this.value = value;
+        ensure(Timestamp.name, value, isDefined(), isInstanceOf(Date));
+    }
+    diff(another) {
+        ensure('timestamp', another, isDefined());
+        return new Duration(Math.abs(this.toMilliseconds() - another.toMilliseconds()));
+    }
+    plus(duration) {
+        ensure('duration', duration, isDefined());
+        return new Timestamp(new Date(this.toMilliseconds() + duration.inMilliseconds()));
+    }
+    less(duration) {
+        ensure('duration', duration, isDefined());
+        return new Timestamp(new Date(this.toMilliseconds() - duration.inMilliseconds()));
+    }
+    isBefore(another) {
+        ensure('timestamp', another, isDefined());
+        return this.value.getTime() < another.value.getTime();
+    }
+    isBeforeOrEqual(another) {
+        ensure('timestamp', another, isDefined());
+        return this.value.getTime() <= another.value.getTime();
+    }
+    isAfter(another) {
+        ensure('timestamp', another, isDefined());
+        return this.value.getTime() > another.value.getTime();
+    }
+    isAfterOrEqual(another) {
+        ensure('timestamp', another, isDefined());
+        return this.value.getTime() >= another.value.getTime();
+    }
+    toMilliseconds() {
+        return this.value.getTime();
+    }
+    toSeconds() {
+        return Math.floor(this.toMilliseconds() / 1_000);
+    }
+    toJSON() {
+        return this.value.toJSON();
+    }
+    toISOString() {
+        return this.value.toISOString();
+    }
+    toString() {
+        return this.toISOString();
+    }
+    [inspect.custom]() {
+        return `Timestamp(${this.value.toISOString()})`;
+    }
+}
+/**
+ * Based on the implementation by Brock Adams:
+ * - https://stackoverflow.com/a/3143231/264502 by Brock Adams
+ * - https://www.w3.org/TR/NOTE-datetime
+ */
+function isSerialisedISO8601Date() {
+    const yyyyMMdd = `\\d{4}-[01]\\d-[0-3]\\d`;
+    const hh = `[0-2]\\d`;
+    const mm = `[0-5]\\d`;
+    const ss = `[0-5]\\d`;
+    const ms = `\\d+`;
+    const T = `[Tt\\s]`;
+    const offset = `[+-]${hh}:${mm}|Z`;
+    const pattern = new RegExp('^' + [
+        // Full precision - YYYY-MM-DDThh:mm:ss.sss
+        `(${yyyyMMdd}${T}${hh}:${mm}:${ss}\\.${ms}(${offset})?)`,
+        // No milliseconds - YYYY-MM-DDThh:mm:ss
+        `(${yyyyMMdd}${T}${hh}:${mm}:${ss}(${offset})?)`,
+        // No seconds - YYYY-MM-DDThh:mm
+        `(${yyyyMMdd}${T}${hh}:${mm}(${offset})?)`,
+        // Just the date - YYYY-MM-DD
+        `(${yyyyMMdd})`,
+    ].join('|') + '$');
+    return Predicate.to(`follow the ISO8601 format: YYYY-MM-DD[Thh:mm[:ss[.sss]]]`, (value) => {
+        if (!pattern.test(value)) {
+            return false;
+        }
+        const date = new Date(value);
+        return date instanceof Date
+            && !Number.isNaN(date.getTime());
+    });
+}
+//# sourceMappingURL=Timestamp.js.map

package/esm/screenplay/time/models/Timestamp.js.map

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

package/esm/screenplay/time/models/index.d.ts

@@ -0,0 +1,7 @@
+export * from './Clock.js';
+export * from './DelayedCallback.js';
+export * from './Duration.js';
+export * from './RepeatUntilLimits.js';
+export * from './Scheduler.js';
+export * from './Timestamp.js';
+//# sourceMappingURL=index.d.ts.map

package/esm/screenplay/time/models/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/time/models/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}

package/esm/screenplay/time/models/index.js

@@ -0,0 +1,7 @@
+export * from './Clock.js';
+export * from './DelayedCallback.js';
+export * from './Duration.js';
+export * from './RepeatUntilLimits.js';
+export * from './Scheduler.js';
+export * from './Timestamp.js';
+//# sourceMappingURL=index.js.map

package/esm/screenplay/time/models/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/screenplay/time/models/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}

package/esm/stage/Cast.d.ts

@@ -0,0 +1,172 @@
+import type { Actor } from '../screenplay/index.js';
+/**
+ * Serenity/JS uses the concept of a _**cast of actors**_ to centralise the process of configuring the [actors](https://serenity-js.org/api/core/class/Actor/) and assigning their [abilities](https://serenity-js.org/api/core/class/Ability/).
+ *
+ * When you invoke [`actorCalled`](https://serenity-js.org/api/core/function/actorCalled/) for the first time in a test scenario,
+ * Serenity/JS [instantiates a new actor](https://serenity-js.org/api/core/class/Actor/)
+ * and passes it through the [`Cast.prepare`](https://serenity-js.org/api/core/class/Cast/#prepare) method.
+ * Specifying a **custom cast** gives you an opportunity to configure the actor with the abilities
+ * they need before it's returned to the caller,
+ * or configure the actors differently **depending on their name**.
+ * It also helps you to avoid having to configure abilities individually in every test scenario.
+ *
+ * :::tip Remember
+ * A **cast** is responsible for assigning **abilities** to **actors** in a central location.
+ * :::
+ *
+ * ## Configuring a cast of actors for the entire test suite
+ *
+ * When working with relatively **simple scenarios** where all the actors should always receive the same set of abilities,
+ * you can [`engage`](https://serenity-js.org/api/core/function/engage/) Serenity/JS to use a generic [`Cast.where`](https://serenity-js.org/api/core/class/Cast/#where):
+ *
+ * ```typescript
+ * import { Cast, configure } from '@serenity-js/core'
+ * import { CallAnApi } from '@serenity-js/rest'
+ *
+ * configure({
+ *   actors: Cast.where(actor => actor.whoCan(
+ *     CallAnApi.at('http://api.example.org'),
+ *     // other abilities
+ *   ))
+ * })
+ * ```
+ *
+ * If you're using Serenity/JS with one of the [supported test runners](https://serenity-js.org/handbook/test-runners/),
+ * you might prefer to use your test runner's native configuration mechanism
+ * instead of invoking [`engage`](https://serenity-js.org/api/core/function/engage/) explicitly.
+ *
+ * :::tip configure vs engage
+ * Calling [`configure`](https://serenity-js.org/api/core/function/configure/) resets the entire Serenity/JS configuration
+ * and should be done exactly once in your entire test suite.
+ * If you want to retain the configuration but reset the cast, use [`engage`](https://serenity-js.org/api/core/function/engage/) instead.
+ * :::
+ *
+ * Learn more about configuring Serenity/JS with:
+ * - [Cucumber.js](https://serenity-js.org/handbook/test-runners/cucumber)
+ * - [Jasmine](https://serenity-js.org/handbook/test-runners/jasmine)
+ * - [Mocha](https://serenity-js.org/handbook/test-runners/mocha)
+ * - [Playwright Test](https://serenity-js.org/handbook/test-runners/playwright-test)
+ * - [Protractor](https://serenity-js.org/handbook/test-runners/protractor)
+ * - [WebdriverIO](https://serenity-js.org/handbook/test-runners/webdriverio)
+ *
+ * ## Engaging a cast of actors for the specific scenario
+ *
+ * If you want to retain Serenity/JS configuration, but set a different [cast](https://serenity-js.org/api/core/class/Cast/)
+ * for the given test scenario you should use [`engage`](https://serenity-js.org/api/core/function/engage/) instead of [`configure`](https://serenity-js.org/api/core/function/configure/).
+ *
+ * This approach is useful for example when your entire test suite is dedicated to interacting with the system
+ * under test via its REST APIs, and you have a handful of scenarios that need a web browser.
+ *
+ * ```ts
+ * import { describe, beforeEach } from 'mocha'
+ * import { engage, Cast } from '@serenity-js/core';
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * describe('My UI feature', () => {
+ *   beforeEach(async () => {
+ *     const browser = await chromium.launch({ headless: true })
+ *     engage(Cast.where(actor => actor.whoCan(BrowseTheWebWithPlaywright.using(browser))))
+ *   })
+ *
+ *   // test scenarios
+ * })
+ * ```
+ *
+ * ## Writing custom casts for complex scenarios
+ *
+ * In **complex scenarios** that involve multiple **actors with different abilities**,
+ * you should create a custom implementation of the [cast](https://serenity-js.org/api/core/class/Cast/).
+ *
+ * Examples of such scenarios include those where actors use separate browser instances, interact with different REST APIs,
+ * or start with different data in their [notepads](https://serenity-js.org/api/core/class/Notepad/).
+ *
+ * ### Defining a custom cast of actors interacting with a Web UI
+ *
+ * ```ts
+ * import { beforeEach } from 'mocha'
+ * import { engage, Actor, Cast } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright, ExtraBrowserContextOptions } from '@serenity-js/playwright'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * export class UIActors implements Cast {
+ *   constructor(
+ *     private readonly browser: Browser,
+ *     private readonly options?: ExtraBrowserContextOptions,
+ *   ) {
+ *   }
+ *
+ *   prepare(actor: Actor): Actor {
+ *     return actor.whoCan(
+ *       BrowseTheWebWithPlaywright.using(this.browser, this.options),
+ *     )
+ *   }
+ * }
+ *
+ * beforeEach(async () => {
+ *   const browser = await chromium.launch({ headless: true })
+ *   engage(new UIActors(browser));
+ * });
+ * ```
+ *
+ * ### Preparing actors differently based on their name
+ *
+ * ```ts
+ * import { beforeEach } from 'mocha'
+ * import { actorCalled, engage, Cast } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright, ExtraBrowserContextOptions } from '@serenity-js/playwright'
+ * import { CallAnApi } from '@serenity-js/rest'
+ * import { Browser, BrowserContextOptions, chromium } from 'playwright'
+ *
+ * class Actors implements Cast {
+ *   constructor(
+ *     private readonly browser: Browser,
+ *     private readonly contextOptions: BrowserContextOptions,
+ *     private readonly extraContextOptions: ExtraBrowserContextOptions,
+ *   ) {
+ *   }
+ *
+ *   prepare(actor: Actor) {
+ *     switch (actor.name) {
+ *       case 'James':
+ *         return actor.whoCan(BrowseTheWebWithPlaywright.using(
+ *           this.browser,
+ *           this.contextOptions,
+ *           this.extraContextOptions
+ *         ));
+ *       default:
+ *         return actor.whoCan(CallAnApi.at(this.contextOptions.baseURL));
+ *     }
+ *   }
+ * }
+ *
+ * beforeEach(async () => {
+ *   const browser = await chromium.launch({ headless: true })
+ *   engage(new Actors(browser, { baseURL: 'https://example.org' }));
+ * });
+ *
+ * actorCalled('James') // returns an actor using a browser
+ * actorCalled('Alice') // returns an actor interacting with an API
+ * ```
+ *
+ * @group Stage
+ */
+export declare abstract class Cast {
+    /**
+     * Creates a generic `Cast` implementation, where new actors receive the abilities
+     * configured by the `prepareFunction`.
+     *
+     * @param prepareFunction
+     */
+    static where(prepareFunction: (actor: Actor) => Actor): Cast;
+    /**
+     * Configures an [`Actor`](https://serenity-js.org/api/core/class/Actor/) instantiated when [`Stage.actor`](https://serenity-js.org/api/core/class/Stage/#actor) is invoked.
+     *
+     * @param actor
+     *
+     * #### Learn more
+     * - [`engage`](https://serenity-js.org/api/core/function/engage/)
+     */
+    abstract prepare(actor: Actor): Actor;
+}
+//# sourceMappingURL=Cast.d.ts.map

package/esm/stage/Cast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cast.d.ts","sourceRoot":"","sources":["../../src/stage/Cast.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuJG;AACH,8BAAsB,IAAI;IAEtB;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,GAAG,IAAI;IAQ5D;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK;CACxC"}

package/esm/stage/Cast.js

@@ -0,0 +1,168 @@
+/**
+ * Serenity/JS uses the concept of a _**cast of actors**_ to centralise the process of configuring the [actors](https://serenity-js.org/api/core/class/Actor/) and assigning their [abilities](https://serenity-js.org/api/core/class/Ability/).
+ *
+ * When you invoke [`actorCalled`](https://serenity-js.org/api/core/function/actorCalled/) for the first time in a test scenario,
+ * Serenity/JS [instantiates a new actor](https://serenity-js.org/api/core/class/Actor/)
+ * and passes it through the [`Cast.prepare`](https://serenity-js.org/api/core/class/Cast/#prepare) method.
+ * Specifying a **custom cast** gives you an opportunity to configure the actor with the abilities
+ * they need before it's returned to the caller,
+ * or configure the actors differently **depending on their name**.
+ * It also helps you to avoid having to configure abilities individually in every test scenario.
+ *
+ * :::tip Remember
+ * A **cast** is responsible for assigning **abilities** to **actors** in a central location.
+ * :::
+ *
+ * ## Configuring a cast of actors for the entire test suite
+ *
+ * When working with relatively **simple scenarios** where all the actors should always receive the same set of abilities,
+ * you can [`engage`](https://serenity-js.org/api/core/function/engage/) Serenity/JS to use a generic [`Cast.where`](https://serenity-js.org/api/core/class/Cast/#where):
+ *
+ * ```typescript
+ * import { Cast, configure } from '@serenity-js/core'
+ * import { CallAnApi } from '@serenity-js/rest'
+ *
+ * configure({
+ *   actors: Cast.where(actor => actor.whoCan(
+ *     CallAnApi.at('http://api.example.org'),
+ *     // other abilities
+ *   ))
+ * })
+ * ```
+ *
+ * If you're using Serenity/JS with one of the [supported test runners](https://serenity-js.org/handbook/test-runners/),
+ * you might prefer to use your test runner's native configuration mechanism
+ * instead of invoking [`engage`](https://serenity-js.org/api/core/function/engage/) explicitly.
+ *
+ * :::tip configure vs engage
+ * Calling [`configure`](https://serenity-js.org/api/core/function/configure/) resets the entire Serenity/JS configuration
+ * and should be done exactly once in your entire test suite.
+ * If you want to retain the configuration but reset the cast, use [`engage`](https://serenity-js.org/api/core/function/engage/) instead.
+ * :::
+ *
+ * Learn more about configuring Serenity/JS with:
+ * - [Cucumber.js](https://serenity-js.org/handbook/test-runners/cucumber)
+ * - [Jasmine](https://serenity-js.org/handbook/test-runners/jasmine)
+ * - [Mocha](https://serenity-js.org/handbook/test-runners/mocha)
+ * - [Playwright Test](https://serenity-js.org/handbook/test-runners/playwright-test)
+ * - [Protractor](https://serenity-js.org/handbook/test-runners/protractor)
+ * - [WebdriverIO](https://serenity-js.org/handbook/test-runners/webdriverio)
+ *
+ * ## Engaging a cast of actors for the specific scenario
+ *
+ * If you want to retain Serenity/JS configuration, but set a different [cast](https://serenity-js.org/api/core/class/Cast/)
+ * for the given test scenario you should use [`engage`](https://serenity-js.org/api/core/function/engage/) instead of [`configure`](https://serenity-js.org/api/core/function/configure/).
+ *
+ * This approach is useful for example when your entire test suite is dedicated to interacting with the system
+ * under test via its REST APIs, and you have a handful of scenarios that need a web browser.
+ *
+ * ```ts
+ * import { describe, beforeEach } from 'mocha'
+ * import { engage, Cast } from '@serenity-js/core';
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * describe('My UI feature', () => {
+ *   beforeEach(async () => {
+ *     const browser = await chromium.launch({ headless: true })
+ *     engage(Cast.where(actor => actor.whoCan(BrowseTheWebWithPlaywright.using(browser))))
+ *   })
+ *
+ *   // test scenarios
+ * })
+ * ```
+ *
+ * ## Writing custom casts for complex scenarios
+ *
+ * In **complex scenarios** that involve multiple **actors with different abilities**,
+ * you should create a custom implementation of the [cast](https://serenity-js.org/api/core/class/Cast/).
+ *
+ * Examples of such scenarios include those where actors use separate browser instances, interact with different REST APIs,
+ * or start with different data in their [notepads](https://serenity-js.org/api/core/class/Notepad/).
+ *
+ * ### Defining a custom cast of actors interacting with a Web UI
+ *
+ * ```ts
+ * import { beforeEach } from 'mocha'
+ * import { engage, Actor, Cast } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright, ExtraBrowserContextOptions } from '@serenity-js/playwright'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * export class UIActors implements Cast {
+ *   constructor(
+ *     private readonly browser: Browser,
+ *     private readonly options?: ExtraBrowserContextOptions,
+ *   ) {
+ *   }
+ *
+ *   prepare(actor: Actor): Actor {
+ *     return actor.whoCan(
+ *       BrowseTheWebWithPlaywright.using(this.browser, this.options),
+ *     )
+ *   }
+ * }
+ *
+ * beforeEach(async () => {
+ *   const browser = await chromium.launch({ headless: true })
+ *   engage(new UIActors(browser));
+ * });
+ * ```
+ *
+ * ### Preparing actors differently based on their name
+ *
+ * ```ts
+ * import { beforeEach } from 'mocha'
+ * import { actorCalled, engage, Cast } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright, ExtraBrowserContextOptions } from '@serenity-js/playwright'
+ * import { CallAnApi } from '@serenity-js/rest'
+ * import { Browser, BrowserContextOptions, chromium } from 'playwright'
+ *
+ * class Actors implements Cast {
+ *   constructor(
+ *     private readonly browser: Browser,
+ *     private readonly contextOptions: BrowserContextOptions,
+ *     private readonly extraContextOptions: ExtraBrowserContextOptions,
+ *   ) {
+ *   }
+ *
+ *   prepare(actor: Actor) {
+ *     switch (actor.name) {
+ *       case 'James':
+ *         return actor.whoCan(BrowseTheWebWithPlaywright.using(
+ *           this.browser,
+ *           this.contextOptions,
+ *           this.extraContextOptions
+ *         ));
+ *       default:
+ *         return actor.whoCan(CallAnApi.at(this.contextOptions.baseURL));
+ *     }
+ *   }
+ * }
+ *
+ * beforeEach(async () => {
+ *   const browser = await chromium.launch({ headless: true })
+ *   engage(new Actors(browser, { baseURL: 'https://example.org' }));
+ * });
+ *
+ * actorCalled('James') // returns an actor using a browser
+ * actorCalled('Alice') // returns an actor interacting with an API
+ * ```
+ *
+ * @group Stage
+ */
+export class Cast {
+    /**
+     * Creates a generic `Cast` implementation, where new actors receive the abilities
+     * configured by the `prepareFunction`.
+     *
+     * @param prepareFunction
+     */
+    static where(prepareFunction) {
+        return new class GenericCast extends Cast {
+            prepare(actor) {
+                return prepareFunction(actor);
+            }
+        };
+    }
+}
+//# sourceMappingURL=Cast.js.map

package/esm/stage/Cast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cast.js","sourceRoot":"","sources":["../../src/stage/Cast.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuJG;AACH,MAAM,OAAgB,IAAI;IAEtB;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,eAAwC;QACjD,OAAO,IAAI,MAAM,WAAY,SAAQ,IAAI;YACrC,OAAO,CAAC,KAAY;gBAChB,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;YAClC,CAAC;SACJ,CAAA;IACL,CAAC;CAWJ"}

package/esm/stage/Extras.d.ts

@@ -0,0 +1,9 @@
+import type { Actor } from '../screenplay/index.js';
+import type { Cast } from './Cast.js';
+/**
+ * Produces no-op actors with no special [`Ability`](https://serenity-js.org/api/core/class/Ability/)
+ */
+export declare class Extras implements Cast {
+    prepare(actor: Actor): Actor;
+}
+//# sourceMappingURL=Extras.d.ts.map

package/esm/stage/Extras.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Extras.d.ts","sourceRoot":"","sources":["../../src/stage/Extras.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC;;GAEG;AACH,qBAAa,MAAO,YAAW,IAAI;IAC/B,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK;CAG/B"}

package/esm/stage/Extras.js

@@ -0,0 +1,9 @@
+/**
+ * Produces no-op actors with no special [`Ability`](https://serenity-js.org/api/core/class/Ability/)
+ */
+export class Extras {
+    prepare(actor) {
+        return actor;
+    }
+}
+//# sourceMappingURL=Extras.js.map

package/esm/stage/Extras.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Extras.js","sourceRoot":"","sources":["../../src/stage/Extras.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,OAAO,MAAM;IACf,OAAO,CAAC,KAAY;QAChB,OAAO,KAAK,CAAC;IACjB,CAAC;CACJ"}

package/esm/stage/ListensToDomainEvents.d.ts

@@ -0,0 +1,23 @@
+import type { DomainEvent } from '../events/index.js';
+/**
+ * A [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/) that can listen and react to [Serenity/JS domain events](https://serenity-js.org/api/core-events/class/DomainEvent/)
+ *
+ * ## Learn more
+ *
+ * - [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/)
+ * - [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMemberBuilder/)
+ * - [`engage`](https://serenity-js.org/api/core/function/engage/)
+ * - [`SerenityConfig.crew`](https://serenity-js.org/api/core/class/SerenityConfig/#crew)
+ *
+ * @group Stage
+ */
+export interface ListensToDomainEvents {
+    /**
+     * Handles [`DomainEvent`](https://serenity-js.org/api/core-events/class/DomainEvent/) objects emitted by the [`Stage`](https://serenity-js.org/api/core/class/Stage/)
+     * that this [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/) is assigned to.
+     *
+     * @param event
+     */
+    notifyOf(event: DomainEvent): void;
+}
+//# sourceMappingURL=ListensToDomainEvents.d.ts.map

package/esm/stage/ListensToDomainEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ListensToDomainEvents.d.ts","sourceRoot":"","sources":["../../src/stage/ListensToDomainEvents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IAElC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;CACtC"}

package/esm/stage/ListensToDomainEvents.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ListensToDomainEvents.js.map

package/esm/stage/ListensToDomainEvents.js.map

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