@serenity-js/core 3.41.2 → 3.42.1

package/esm/screenplay/notes/Notepad.js

@@ -0,0 +1,197 @@
+import { TinyType } from 'tiny-types';
+import { LogicError } from '../../errors/index.js';
+import { d } from '../../io/index.js';
+import { NotepadAdapter } from './NotepadAdapter.js';
+/**
+ * Stores notes recorded by an [`Actor`](https://serenity-js.org/api/core/class/Actor/).
+ *
+ * See [`TakeNotes`](https://serenity-js.org/api/core/class/TakeNotes/) and [notes](https://serenity-js.org/api/core/function/notes) for more usage examples.
+ *
+ * ## Sharing a notepad between actors
+ *
+ * ```ts
+ * import { Actor, Cast, Notepad, TakeNotes } from '@serenity-js/core'
+ *
+ * interface MyNotes {
+ *   auth: {
+ *     username: string;
+ *     password: string;
+ *   }
+ * }
+ *
+ * export class Actors implements Cast {
+ *
+ *   // initialise a shared notepad when the Actors class is initialised
+ *   private readonly sharedNotepad = Notepad.with<MyNotes>({
+ *     auth: {
+ *       username: 'test-user',
+ *       password: 'SuperSecretP@ssword!',
+ *     }
+ *   });
+ *
+ *   prepare(actor: Actor): Actor {
+ *     switch (actor.name) {
+ *       case 'Alice':
+ *       case 'Bob':
+ *         // Alice and Bob will share their notepad
+ *         return actor.whoCan(TakeNotes.using(this.sharedNotepad));
+ *       default:
+ *         // other actors will get their own notepads
+ *         return actor.whoCan(TakeNotes.using(Notepad.empty<AuthCredentials>()));
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [`TakeNotes`](https://serenity-js.org/api/core/class/TakeNotes/)
+ * - [notes](https://serenity-js.org/api/core/function/notes)
+ * - [`Cast`](https://serenity-js.org/api/core/class/Cast/)
+ *
+ * @group Notes
+ */
+export class Notepad extends TinyType {
+    recordedNotes;
+    /**
+     * Instantiates a new empty Notepad.
+     */
+    static empty() {
+        return new Notepad({});
+    }
+    /**
+     * Instantiates a new Notepad with an initial state.
+     *
+     * ```ts
+     * import { actorCalled, Notepad, notes, TakeNotes } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     * interface MyNotes {
+     *   personalDetails: {
+     *     firstName: string;
+     *     lastName: string;
+     *   }
+     * }
+     *
+     * actorCalled('Leonard')
+     *   .whoCan(
+     *     TakeNotes.using(
+     *       Notepad.with<MyNotes>({
+     *         personalDetails: {
+     *           firstName: 'Leonard',
+     *           lastName: 'McLaud',
+     *         }
+     *       })
+     *     )
+     *   )
+     *   .attemptsTo(
+     *     Ensure.that(
+     *       notes<MyNotes>().get('personalDetails').firstName,
+     *       equals('Leonard')
+     *     ),
+     *   )
+     * ```
+     *
+     * @param notes
+     */
+    static with(notes) {
+        return new Notepad(notes);
+    }
+    /**
+     * Creates a [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that simplifies access to the notes
+     * stored in this notepad. Allows the [`Actor`](https://serenity-js.org/api/core/class/Actor/) to record, read, and remove notes.
+     *
+     * #### Learn more
+     * - [notes](https://serenity-js.org/api/core/function/notes)
+     * - [`TakeNotes`](https://serenity-js.org/api/core/class/TakeNotes/)
+     * - [`Notepad`](https://serenity-js.org/api/core/class/Notepad/)
+     */
+    static notes() {
+        return new NotepadAdapter();
+    }
+    /**
+     * Instantiates a [`Notepad`](https://serenity-js.org/api/core/class/Notepad/) with an initial state.
+     *
+     * @param recordedNotes
+     *  Initial state of the notepad
+     */
+    constructor(recordedNotes) {
+        super();
+        this.recordedNotes = recordedNotes;
+    }
+    /**
+     * Checks if a note identified by `subject` exists in the notepad.
+     *
+     * @param subject
+     *   A subject (name) that uniquely identifies a given note
+     *
+     * @returns
+     *  `true` if the note exists, `false` otherwise
+     */
+    has(subject) {
+        return Object.prototype.hasOwnProperty.call(this.recordedNotes, subject);
+    }
+    /**
+     * Retrieves a note, identified by `subject`, from the notepad.
+     *
+     * @param subject
+     *   A subject (name) that uniquely identifies a given note
+     *
+     * @returns
+     *  The value of the previously recorded note.
+     *
+     * @throws [`LogicError`](https://serenity-js.org/api/core/class/LogicError/)
+     *  Throws a [`LogicError`](https://serenity-js.org/api/core/class/LogicError/) if the note with a given `subject`
+     *  has never been recorded.
+     */
+    get(subject) {
+        if (!this.has(subject)) {
+            throw new LogicError(d `Note of ${subject} cannot be retrieved because it's never been recorded`);
+        }
+        return this.recordedNotes[subject];
+    }
+    /**
+     * Stores a given `value` uniquely identified by `subject` in the notepad.
+     *
+     * @param subject
+     *  A subject (name) that uniquely identifies a given note
+     *
+     * @param value
+     *  The value to record.
+     */
+    set(subject, value) {
+        this.recordedNotes[subject] = value;
+        return this;
+    }
+    /**
+     * Removes the note identified by `subject` from the notepad.
+     *
+     * @param subject
+     *
+     * @returns
+     *  `true` if the item in the Notepad object existed and has been removed,
+     *  `false` otherwise.
+     */
+    delete(subject) {
+        if (this.has(subject)) {
+            return delete this.recordedNotes[subject];
+        }
+        return false;
+    }
+    /**
+     * Deletes all the notes stored in this notepad.
+     */
+    clear() {
+        const keys = Object.keys(this.recordedNotes);
+        for (const key of keys) {
+            this.delete(key);
+        }
+    }
+    /**
+     * Returns the number of notes stored in the notepad.
+     */
+    size() {
+        return Object.keys(this.recordedNotes).length;
+    }
+}
+//# sourceMappingURL=Notepad.js.map

package/esm/screenplay/notes/Notepad.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Notepad.js","sourceRoot":"","sources":["../../../src/screenplay/notes/Notepad.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,OAAO,OAAwC,SAAQ,QAAQ;IAmE1B;IAjEvC;;OAEG;IACH,MAAM,CAAC,KAAK;QACR,OAAO,IAAI,OAAO,CAAI,EAAO,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,MAAM,CAAC,IAAI,CAA6B,KAAQ;QAC5C,OAAO,IAAI,OAAO,CAAI,KAAK,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK;QACR,OAAO,IAAI,cAAc,EAAK,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,YAAuC,aAAoB;QACvD,KAAK,EAAE,CAAC;QAD2B,kBAAa,GAAb,aAAa,CAAO;IAE3D,CAAC;IAED;;;;;;;;OAQG;IACH,GAAG,CAA8B,OAAgB;QAC7C,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAC7E,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,GAAG,CAA8B,OAAgB;QAC7C,IAAI,CAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,UAAU,CAAC,CAAC,CAAA,WAAY,OAAQ,uDAAuD,CAAC,CAAC;QACvG,CAAC;QAED,OAAO,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;;;OAQG;IACH,GAAG,CAA8B,OAAgB,EAAE,KAAqB;QACpE,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;QACpC,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAA8B,OAAgB;QAChD,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACpB,OAAO,OAAO,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,KAAK;QACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAE7C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACL,CAAC;IAED;;OAEG;IACH,IAAI;QACA,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC;IAClD,CAAC;CACJ"}

package/esm/screenplay/notes/NotepadAdapter.d.ts

@@ -0,0 +1,245 @@
+import type { JSONObject } from 'tiny-types';
+import type { Answerable } from '../Answerable.js';
+import { Interaction } from '../Interaction.js';
+import type { QuestionAdapter } from '../Question.js';
+import type { ChainableSetter } from './ChainableSetter.js';
+/**
+ * Serenity/JS Screenplay Pattern-style adapter for the [`Notepad`](https://serenity-js.org/api/core/class/Notepad/),
+ * that makes it easier for the [actors](https://serenity-js.org/api/core/class/Actor/) to access its APIs.
+ *
+ * See [`TakeNotes`](https://serenity-js.org/api/core/class/TakeNotes/), [`Notepad`](https://serenity-js.org/api/core/class/Notepad/) and [`notes`](https://serenity-js.org/api/core/function/notes/) for more examples.
+ *
+ * @group Notes
+ */
+export declare class NotepadAdapter<Notes extends Record<any, any>> implements ChainableSetter<Notes> {
+    /**
+     * Checks if a note identified by `subject` exists in the notepad.
+     *
+     * #### Learn more
+     * - [`Notepad.has`](https://serenity-js.org/api/core/class/Notepad/#has)}
+     *
+     * @param subject
+     *   A subject (name) that uniquely identifies a given note
+     *
+     * @returns
+     *  Question that resolves to `true` if the note exists, `false` otherwise
+     */
+    has<Subject extends keyof Notes>(subject: Subject): QuestionAdapter<boolean>;
+    /**
+     * Retrieves a note, identified by `subject`, from the notepad.
+     *
+     * #### Learn more
+     * - [`Notepad.get`](https://serenity-js.org/api/core/class/Notepad/#get)}
+     *
+     * @param subject
+     *   A subject (name) that uniquely identifies a given note
+     *
+     * @returns
+     *  The value of the previously recorded note.
+     *
+     * @throws
+     *  Throws a [`LogicError`](https://serenity-js.org/api/core/class/LogicError/) if the note with a given `subject`
+     *  has never been recorded.
+     */
+    get<Subject extends keyof Notes>(subject: Subject): QuestionAdapter<Notes[Subject]>;
+    /**
+     * Resolves a given `Answerable<value>` and stores it in the notepad,
+     * uniquely identified by its `subject`.
+     *
+     * **Pro tip:** calls to `set` can be chained and result in an accumulation
+     * of values to be recorded in the [`Notepad`](https://serenity-js.org/api/core/class/Notepad/).
+     * Those values are resolved and recorded when the [`Interaction`](https://serenity-js.org/api/core/class/Interaction/)
+     * returned by this method is performed by an [`Actor`](https://serenity-js.org/api/core/class/Actor/).
+     *
+     * If a note identified by a given `subject` is set multiple times,
+     * the last call wins.
+     *
+     * ```ts
+     *  import { actorCalled, notes, TakeNotes } from '@serenity-js/core'
+     *  import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     *  interface MyNotes {
+     *      stringNote: string;
+     *      numberNote: number;
+     *  }
+     *
+     * await actorCalled('Alice')
+     *   .whoCan(TakeNotes.usingAnEmptyNotepad<MyNotes>());
+     *   .attemptsTo(
+     *
+     *     notes<MyNotes>()
+     *       .set('stringNote', 'example')
+     *       .set('numberNote', Promise.resolve(42))
+     *       .set('stringNote', 'another example'),
+     *
+     *     Ensure.equal(notes().toJSON(), {
+     *       firstNote: 'another example',
+     *       secondNote: 42,
+     *     })
+     * )
+     * ```
+     *
+     * #### Learn more
+     * - [`Notepad.set`](https://serenity-js.org/api/core/class/Notepad/#set)
+     *
+     * @param subject
+     *   A subject (name) that uniquely identifies a given note
+     *
+     * @param value
+     *  The value to record
+     */
+    set<Subject extends keyof Notes>(subject: Subject, value: Answerable<Notes[Subject]>): ChainableSetter<Notes> & Interaction;
+    /**
+     * Removes the note identified by `subject` from the notepad.
+     *
+     * #### Using as an `Interaction`
+     *
+     * ```ts
+     * import { actorCalled, Check, Log, notes } from '@serenity-js/core'
+     * import { isPresent } from '@serenity-js/assertions'
+     *
+     * interface MyNotes {
+     *   myNote: string;
+     * }
+     *
+     * await actorCalled('Alice')
+     *   .whoCan(TakeNotes.using(Notepad.empty<MyNotes>()))
+     *   .attemptsTo(
+     *     notes<MyNotes>().set('myNote', 'example value'),
+     *
+     *     notes<MyNotes>().delete('myNote'),
+     *
+     *     Check.whether(notes<MyNotes>().get('myNote'), isPresent())
+     *       .andIfSo(
+     *         Log.the('myNote is present'),
+     *       )
+     *       .otherwise(
+     *         Log.the('myNote was deleted'),
+     *       )
+     *   )
+     *   // logs: myNote was deleted
+     * ```
+     *
+     * #### Using as a `Question`
+     *
+     * ```ts
+     * import { actorCalled, Check, Log, notes } from '@serenity-js/core'
+     * import { isTrue } from '@serenity-js/assertions'
+     *
+     * interface MyNotes {
+     *   myNote: string;
+     * }
+     *
+     * await actorCalled('Alice')
+     *   .whoCan(TakeNotes.using(Notepad.empty<MyNotes>()))
+     *   .attemptsTo(
+     *     notes<MyNotes>().set('myNote', 'example value'),
+     *
+     *     Check.whether(notes<MyNotes>().delete('myNote'), isTrue())
+     *       .andIfSo(
+     *         Log.the('myNote was deleted'),
+     *       )
+     *       .otherwise(
+     *         Log.the('myNote could not be deleted because it was not set'),
+     *       )
+     *   )
+     *   // logs: myNote was deleted
+     * ```
+     *
+     * #### Learn more
+     * - [`Notepad.delete`](https://serenity-js.org/api/core/class/Notepad/#delete)
+     *
+     * @param subject
+     *
+     * @returns
+     *  When used as a `Question`, resolves to `true` if the item in the Notepad object existed and has been removed,
+     *  `false` otherwise.
+     */
+    delete<Subject extends keyof Notes>(subject: Subject): QuestionAdapter<boolean>;
+    /**
+     * Deletes all the notes stored in this notepad.
+     *
+     * ```ts
+     * import { actorCalled, notes } from '@serenity-js/core'
+     * import { isTrue } from '@serenity-js/assertions'
+     *
+     * interface MyNotes {
+     *   myNote: string;
+     * }
+     *
+     * await actorCalled('Alice')
+     *   .whoCan(TakeNotes.using(Notepad.empty<MyNotes>()))
+     *   .attemptsTo(
+     *     notes<MyNotes>().set('myNote', 'example value'),
+     *     Log.the(notes<MyNotes>().size()),   // emits 1
+     *     notes<MyNotes>().clear(),
+     *     Log.the(notes<MyNotes>().size()),   // emits 0
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - [`Notepad.clear`](https://serenity-js.org/api/core/class/Notepad/#clear)
+     */
+    clear(): Interaction;
+    /**
+     * Returns the number of notes stored in the notepad.
+     *
+     * ```ts
+     * import { actorCalled, notes } from '@serenity-js/core'
+     * import { isTrue } from '@serenity-js/assertions'
+     *
+     * interface MyNotes {
+     *   myNote: string;
+     * }
+     *
+     * await actorCalled('Alice')
+     *   .whoCan(TakeNotes.using(Notepad.empty<MyNotes>()))
+     *   .attemptsTo(
+     *     Log.the(notes<MyNotes>().size()),   // emits 0
+     *     notes<MyNotes>().set('myNote', 'example value'),
+     *     Log.the(notes<MyNotes>().size()),   // emits 1
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - [`Notepad.size`](https://serenity-js.org/api/core/class/Notepad/#size)
+     */
+    size(): QuestionAdapter<number>;
+    /**
+     * Produces a [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that resolves to a `JSONObject`
+     * representing the resolved notes stored in the notepad.
+     *
+     * Note that serialisation to JSON will simplify some data types that might not be serialisable by default,
+     * but are commonly used in data structures representing actor's notes.
+     * For example a [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) will be serialised as a regular JSON object, a [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) will be serialised as [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).
+     *
+     * Additionally, notepad assumes that the data structure you use it with does not contain cyclic references.
+     *
+     * To learn more about the serialisation mechanism used by the notepad, please refer to [TinyTypes documentation](https://jan-molak.github.io/tiny-types/).
+     *
+     * ```ts
+     * import { actorCalled, notes } from '@serenity-js/core'
+     *
+     * await actorCalled('Alice')
+     *   .whoCan(TakeNotes.using(Notepad.with({
+     *     aSet: new Set(['apples', 'bananas', 'cucumbers']),
+     *     aPromisedValue: Promise.resolve(42),
+     *     aString: 'example'
+     *   })))
+     *   .attemptsTo(
+     *     Log.the(notes().toJSON()),
+     *   )
+     *   // emits: {
+     *   //    aSet: ['apples', 'bananas', 'cucumbers']
+     *   //    aPromisedValue: 42,
+     *   //    aString: 'example',
+     *   // }
+     * ```
+     */
+    toJSON(): QuestionAdapter<JSONObject>;
+    /**
+     * @inheritDoc
+     */
+    toString(): string;
+}
+//# sourceMappingURL=NotepadAdapter.d.ts.map

package/esm/screenplay/notes/NotepadAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotepadAdapter.d.ts","sourceRoot":"","sources":["../../../src/screenplay/notes/NotepadAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAItD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5D;;;;;;;GAOG;AACH,qBAAa,cAAc,CAAC,KAAK,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAE,YAAW,eAAe,CAAC,KAAK,CAAC;IAEzF;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,OAAO,SAAS,MAAM,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC;IAM5E;;;;;;;;;;;;;;;OAeG;IACH,GAAG,CAAC,OAAO,SAAS,MAAM,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAMnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;IACH,GAAG,CAAC,OAAO,SAAS,MAAM,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,GAAG,WAAW;IAI3H;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiEG;IACH,MAAM,CAAC,OAAO,SAAS,MAAM,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC;IAM/E;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,IAAI,WAAW;IAMpB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAI,IAAI,eAAe,CAAC,MAAM,CAAC;IAM/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,IAAI,eAAe,CAAC,UAAU,CAAC;IAMrC;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGrB"}