@serenity-js/core 3.0.0-rc.9 → 3.0.1

package/lib/config/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (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("./ClassDescription"), exports);
+__exportStar(require("./SerenityConfig"), exports);
+//# sourceMappingURL=index.js.map

package/lib/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,mDAAiC"}

package/lib/errors/ErrorFactory.d.ts

@@ -0,0 +1,16 @@
+import { DiffFormatter } from './diff';
+import { ErrorOptions } from './ErrorOptions';
+import { RuntimeError } from './model';
+/**
+ * Generates Serenity/JS {@apilink RuntimeError} objects based on provided {@apilink ErrorOptions|configuration}.
+ *
+ * @group Errors
+ */
+export declare class ErrorFactory {
+    private readonly formatter;
+    constructor(formatter?: DiffFormatter);
+    create<RE extends RuntimeError>(errorType: new (...args: any[]) => RE, options: ErrorOptions): RE;
+    private title;
+    private diffFrom;
+}
+//# sourceMappingURL=ErrorFactory.d.ts.map

package/lib/errors/ErrorFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorFactory.d.ts","sourceRoot":"","sources":["../../src/errors/ErrorFactory.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEvC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;GAIG;AACH,qBAAa,YAAY;IAET,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,GAAE,aAAuC;IAG/E,MAAM,CAAC,EAAE,SAAS,YAAY,EAAE,SAAS,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,EAAE;IAcjG,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,QAAQ;CAMnB"}

package/lib/errors/ErrorFactory.js

@@ -0,0 +1,241 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorFactory = void 0;
+const diff_1 = require("diff");
+const objects_1 = require("tiny-types/lib/objects");
+const util_1 = require("util");
+const io_1 = require("../io");
+const stringified_1 = require("../io/stringified");
+const Unanswered_1 = require("../screenplay/questions/Unanswered");
+const AnsiDiffFormatter_1 = require("./diff/AnsiDiffFormatter");
+/**
+ * Generates Serenity/JS {@apilink RuntimeError} objects based on provided {@apilink ErrorOptions|configuration}.
+ *
+ * @group Errors
+ */
+class ErrorFactory {
+    constructor(formatter = new AnsiDiffFormatter_1.AnsiDiffFormatter()) {
+        this.formatter = formatter;
+    }
+    create(errorType, options) {
+        const message = [
+            this.title(options.message),
+            options.expectation && `\nExpectation: ${options.expectation}`,
+            options.diff && ('\n' + this.diffFrom(options.diff)),
+            options.location && (`    at ${options.location.path.value}:${options.location.line}:${options.location.column}`),
+        ].
+            filter(Boolean).
+            join('\n');
+        return new errorType(message, options === null || options === void 0 ? void 0 : options.cause);
+    }
+    title(value) {
+        return String(value).trim();
+    }
+    diffFrom(diff) {
+        return new Diff(diff.expected, diff.actual)
+            .lines()
+            .map(line => line.decorated(this.formatter))
+            .join('\n');
+    }
+}
+exports.ErrorFactory = ErrorFactory;
+class DiffLine {
+    constructor(type, value) {
+        this.type = type;
+        this.value = value;
+    }
+    prependMarker() {
+        return this.prepend(this.marker());
+    }
+    appendMarker() {
+        return this.append(this.marker());
+    }
+    prepend(text) {
+        return new DiffLine(this.type, String(text) + this.value);
+    }
+    append(text) {
+        return new DiffLine(this.type, this.value + String(text));
+    }
+    decorated(decorator) {
+        return decorator[this.type](this.value);
+    }
+    marker() {
+        return DiffLine.markers[this.type];
+    }
+}
+_a = DiffLine;
+DiffLine.markers = {
+    'expected': '- ',
+    'received': '+ ',
+    'unchanged': '  ',
+};
+DiffLine.empty = () => new DiffLine('unchanged', '');
+DiffLine.unchanged = (line) => new DiffLine('unchanged', String(line));
+DiffLine.expected = (line) => new DiffLine('expected', String(line));
+DiffLine.received = (line) => new DiffLine('received', String(line));
+DiffLine.changed = (change, line) => {
+    if (change.removed) {
+        return _a.expected(line);
+    }
+    if (change.added) {
+        return _a.received(line);
+    }
+    return _a.unchanged(line);
+};
+class DiffValue {
+    constructor(name, value) {
+        this.value = value;
+        this.nameAndType = `${name} ${(0, io_1.typeOf)(value)}`;
+        this.desiredNameFieldLength = this.nameAndType.length;
+        this.summary = this.summaryOf(value);
+    }
+    withDesiredFieldLength(columns) {
+        this.desiredNameFieldLength = columns;
+        return this;
+    }
+    hasSummary() {
+        return this.summary !== undefined;
+    }
+    type() {
+        return (0, io_1.typeOf)(this.value);
+    }
+    isComplex() {
+        return (typeof this.value === 'object' || util_1.types.isProxy(this.value))
+            && !(this.value instanceof RegExp)
+            && !(this.value instanceof Unanswered_1.Unanswered);
+    }
+    isArray() {
+        return Array.isArray(this.value);
+    }
+    isComparableAsJson() {
+        if (!this.value || this.value instanceof Unanswered_1.Unanswered) {
+            return false;
+        }
+        return (0, stringified_1.isPlainObject)(this.value)
+            || this.value['toJSON'];
+    }
+    toString() {
+        const labelWidth = this.desiredNameFieldLength - this.nameAndType.length;
+        return [
+            this.nameAndType,
+            this.summary && ': '.padEnd(labelWidth + 2),
+            this.summary,
+            this.changes && this.changes.padStart(labelWidth + 5),
+        ].
+            filter(Boolean).
+            join('');
+    }
+    summaryOf(value) {
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        const isDefined = value !== undefined && value !== null;
+        if (isDefined && ((0, io_1.isPrimitive)(value) || value instanceof RegExp)) {
+            return String(value);
+        }
+        return undefined;
+    }
+}
+class Diff {
+    constructor(expectedValue, actualValue) {
+        this.diff = this.diffFrom(expectedValue, actualValue);
+    }
+    diffFrom(expectedValue, actualValue) {
+        const { expected, actual } = this.aligned(new DiffValue('Expected', expectedValue), new DiffValue('Received', actualValue));
+        if (this.shouldRenderActualValueOnly(expected, actual)) {
+            return this.renderActualValue(expected, actual);
+        }
+        if (this.shouldRenderJsonDiff(expected, actual)) {
+            return this.renderJsonDiff(expected, actual);
+        }
+        if (this.shouldRenderArrayDiff(expected, actual)) {
+            return this.renderArrayDiff(expected, actual);
+        }
+        return [
+            DiffLine.expected(expected),
+            DiffLine.received(actual),
+            DiffLine.empty(),
+        ];
+    }
+    shouldRenderActualValueOnly(expected, actual) {
+        return actual.isComplex()
+            && !actual.hasSummary()
+            && expected.type() !== actual.type();
+    }
+    shouldRenderJsonDiff(expected, actual) {
+        return expected.isComparableAsJson()
+            && actual.isComparableAsJson()
+            && !expected.hasSummary()
+            && !actual.hasSummary();
+    }
+    shouldRenderArrayDiff(expected, actual) {
+        return expected.isArray()
+            && actual.isArray();
+    }
+    aligned(expected, actual) {
+        const maxFieldLength = Math.max(expected.desiredNameFieldLength, actual.desiredNameFieldLength);
+        return {
+            expected: expected.withDesiredFieldLength(maxFieldLength),
+            actual: actual.withDesiredFieldLength(maxFieldLength)
+        };
+    }
+    renderActualValue(expected, actual) {
+        const lines = (0, io_1.inspected)(actual.value)
+            .split('\n')
+            .map(DiffLine.unchanged);
+        return [
+            DiffLine.expected(expected),
+            DiffLine.received(actual),
+            DiffLine.empty(),
+            ...lines,
+            DiffLine.empty(),
+        ];
+    }
+    renderJsonDiff(expected, actual) {
+        const changes = (0, diff_1.diffJson)(expected.value, actual.value);
+        const lines = changes.reduce((acc, change) => {
+            const changedLines = change.value.trimEnd().split('\n');
+            return acc.concat(changedLines.map(line => DiffLine.changed(change, line).prependMarker()));
+        }, []);
+        const { added, removed } = this.countOf(changes);
+        return [
+            DiffLine.expected(expected).append('  ').appendMarker().append(`${removed}`),
+            DiffLine.received(actual).append('  ').appendMarker().append(`${added}`),
+            DiffLine.empty(),
+            ...lines,
+            DiffLine.empty(),
+        ];
+    }
+    renderArrayDiff(expected, actual) {
+        const changes = (0, diff_1.diffArrays)(expected.value, actual.value, { comparator: objects_1.equal });
+        const lines = changes.reduce((acc, change) => {
+            const items = change.value;
+            return acc.concat(items.map(item => DiffLine.changed(change, (0, io_1.inspected)(item, { compact: true }))
+                .prepend('  ')
+                .prependMarker()));
+        }, []);
+        const { added, removed } = this.countOf(changes);
+        return [
+            DiffLine.expected(expected).append('  ').appendMarker().append(`${removed}`),
+            DiffLine.received(actual).append('  ').appendMarker().append(`${added}`),
+            DiffLine.empty(),
+            DiffLine.unchanged('  ['),
+            ...lines,
+            DiffLine.unchanged('  ]'),
+            DiffLine.empty(),
+        ];
+    }
+    countOf(changes) {
+        return changes.reduce(({ removed, added }, change) => {
+            return {
+                removed: removed + (change.removed ? change.count : 0),
+                added: added + (change.added ? change.count : 0),
+            };
+        }, { removed: 0, added: 0 });
+    }
+    lines() {
+        return this.diff;
+    }
+}
+//# sourceMappingURL=ErrorFactory.js.map

package/lib/errors/ErrorFactory.js.map

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

package/lib/errors/ErrorOptions.d.ts

@@ -0,0 +1,16 @@
+import { FileSystemLocation } from '../io';
+import { ExpectationDetails } from '../screenplay';
+/**
+ * @group Errors
+ */
+export interface ErrorOptions {
+    message: string;
+    location?: FileSystemLocation;
+    expectation?: ExpectationDetails;
+    diff?: {
+        expected: unknown;
+        actual: unknown;
+    };
+    cause?: Error;
+}
+//# sourceMappingURL=ErrorOptions.d.ts.map

package/lib/errors/ErrorOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorOptions.d.ts","sourceRoot":"","sources":["../../src/errors/ErrorOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,IAAI,CAAC,EAAE;QACH,QAAQ,EAAE,OAAO,CAAC;QAClB,MAAM,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,KAAK,CAAC,EAAE,KAAK,CAAC;CACjB"}

package/lib/errors/ErrorOptions.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ErrorOptions.js.map

package/lib/errors/ErrorOptions.js.map

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

package/lib/errors/ErrorSerialiser.d.ts

@@ -0,0 +1,14 @@
+import { JSONObject } from 'tiny-types';
+/**
+ * @group Errors
+ */
+export declare class ErrorSerialiser {
+    private static readonly recognisedErrors;
+    static serialise(error: Error): string;
+    static registerErrorTypes(...types: Array<new (...args: any[]) => Error>): void;
+    static deserialise(serialised?: string | JSONObject): Error | undefined;
+    private static isSerialisable;
+    private static isDeserialisable;
+    static deserialiseFromStackTrace(stack: string): Error;
+}
+//# sourceMappingURL=ErrorSerialiser.d.ts.map

package/lib/errors/ErrorSerialiser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorSerialiser.d.ts","sourceRoot":"","sources":["../../src/errors/ErrorSerialiser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,UAAU,EAAa,MAAM,YAAY,CAAC;AAElF;;GAEG;AACH,qBAAa,eAAe;IACxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAStC;IAEF,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAiBtC,MAAM,CAAC,kBAAkB,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,KAAK,CAAC,GAAG,IAAI;IAQ/E,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,KAAK,GAAG,SAAS;IAwBvE,OAAO,CAAC,MAAM,CAAC,cAAc;IAK7B,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAK/B,MAAM,CAAC,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK;CAWzD"}

package/lib/{io → errors}/ErrorSerialiser.js

@@ -1,10 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ErrorSerialiser = void 0;
-const serenitySpecificErrors = require("../errors");
-const json_1 = require("./json");
+const tiny_types_1 = require("tiny-types");
+/**
+ * @group Errors
+ */
 class ErrorSerialiser {
     static serialise(error) {
+        if (this.isSerialisable(error)) {
+            return JSON.stringify(error.toJSON(), undefined, 0);
+        }
         const name = error && error.constructor && error.constructor.name
             ? error.constructor.name
             : error.name;
@@ -12,11 +17,24 @@ class ErrorSerialiser {
             serialised[key] = error[key];
             return serialised;
         }, { name });
-        return (0, json_1.stringify)(serialisedError);
+        return JSON.stringify(serialisedError, undefined, 0);
+    }
+    static registerErrorTypes(...types) {
+        types.forEach(type => {
+            ErrorSerialiser.recognisedErrors.push((0, tiny_types_1.ensure)(`Error type ${type}`, type, (0, tiny_types_1.isDefined)(), (0, tiny_types_1.isFunction)()));
+        });
     }
-    static deserialise(stringifiedError) {
-        const serialisedError = (0, json_1.parse)(stringifiedError);
+    static deserialise(serialised) {
+        if (serialised === null || serialised === undefined) {
+            return undefined;
+        }
+        const serialisedError = typeof serialised === 'string'
+            ? JSON.parse(serialised)
+            : serialised;
         const constructor = ErrorSerialiser.recognisedErrors.find(errorType => errorType.name === serialisedError.name) || Error;
+        if (this.isDeserialisable(constructor)) {
+            return constructor.fromJSON(serialisedError);
+        }
         const deserialised = Object.create(constructor.prototype);
         for (const property in serialisedError) {
             if (Object.prototype.hasOwnProperty.call(serialisedError, property)) {
@@ -25,18 +43,26 @@ class ErrorSerialiser {
         }
         return deserialised;
     }
+    static isSerialisable(value) {
+        return value
+            && typeof value.toJSON === 'function';
+    }
+    static isDeserialisable(type) {
+        return type
+            && typeof type.fromJSON === 'function';
+    }
     static deserialiseFromStackTrace(stack) {
         const stackTracePattern = /^([^\s:]*Error).*?(?::\s)?(.*?)\n(^ +at.*)$/ms;
         if (!stackTracePattern.test(stack)) {
             return new Error(String(stack));
         }
         const [, name, message, callStack_] = stack.match(stackTracePattern);
-        return ErrorSerialiser.deserialise((0, json_1.stringify)({ name, message: message.trim(), stack }));
+        return ErrorSerialiser.deserialise({ name, message: message.trim(), stack });
     }
 }
 exports.ErrorSerialiser = ErrorSerialiser;
 ErrorSerialiser.recognisedErrors = [
-    ...Object.keys(serenitySpecificErrors).map(key => serenitySpecificErrors[key]),
+    // Built-in JavaScript errors
     Error,
     EvalError,
     RangeError,

package/lib/errors/ErrorSerialiser.js.map

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

package/lib/errors/ErrorStackParser.d.ts

@@ -0,0 +1,13 @@
+import * as parser from 'error-stack-parser';
+/**
+ * A thin wrapper around error-stack-parser module
+ *
+ * ## Learn more
+ * - [Error stack parser](https://www.npmjs.com/package/error-stack-parser)
+ *
+ * @group Errors
+ */
+export declare class ErrorStackParser {
+    parse(error: Error): parser.StackFrame[];
+}
+//# sourceMappingURL=ErrorStackParser.d.ts.map

package/lib/errors/ErrorStackParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorStackParser.d.ts","sourceRoot":"","sources":["../../src/errors/ErrorStackParser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAC;AAE7C;;;;;;;GAOG;AACH,qBAAa,gBAAgB;IACzB,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,UAAU,EAAE;CAG3C"}

package/lib/errors/ErrorStackParser.js

@@ -0,0 +1,42 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorStackParser = void 0;
+const parser = __importStar(require("error-stack-parser"));
+/**
+ * A thin wrapper around error-stack-parser module
+ *
+ * ## Learn more
+ * - [Error stack parser](https://www.npmjs.com/package/error-stack-parser)
+ *
+ * @group Errors
+ */
+class ErrorStackParser {
+    parse(error) {
+        return parser.parse(error);
+    }
+}
+exports.ErrorStackParser = ErrorStackParser;
+//# sourceMappingURL=ErrorStackParser.js.map

package/lib/errors/ErrorStackParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorStackParser.js","sourceRoot":"","sources":["../../src/errors/ErrorStackParser.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,2DAA6C;AAE7C;;;;;;;GAOG;AACH,MAAa,gBAAgB;IACzB,KAAK,CAAC,KAAY;QACd,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;CACJ;AAJD,4CAIC"}

package/lib/errors/RaiseErrors.d.ts

@@ -0,0 +1,57 @@
+import { Ability } from '../screenplay';
+import { Stage } from '../stage';
+import { ErrorOptions } from './ErrorOptions';
+import { RuntimeError } from './model';
+/**
+ * An {@apilink Ability} that enables an {@apilink Actor} to create a Serenity/JS {@apilink RuntimeError}
+ * from within a custom {@apilink Interaction}.
+ *
+ * The stack trace of an error created this way includes the filesystem location pointing to where the interaction was invoked,
+ * which makes debugging any failures easier.
+ *
+ * :::info Pro tip
+ * The ability to `RaiseErrors` is given to all Serenity/JS actors by default, so you don't need to configure it explicitly.
+ * :::
+ *
+ * ## Raising an error
+ *
+ * ```typescript
+ * import { Interaction, LogicError, RaiseErrors } from '@serenity-js/core'
+ * import isPathInside from 'is-path-inside'
+ * import { unlink } from 'fs/promises'
+ *
+ * const RemoveFile = (pathToFile: string) =>
+ *   Interaction.where(`#actor removes a file at ${ pathToFile }`, async actor => {
+ *
+ *     if (! isPathInside(pathToFile, process.cwd())) {
+ *
+ *       throw RaiseErrors.as(actor).create(LogicError, {
+ *         message: `Removing files outside the current working directory is not allowed`
+ *         diff: {
+ *           expected: process.cwd(),
+ *           actual: pathToFile,
+ *         }
+ *       })
+ *     }
+ *
+ *     await unlink(pathToFile);
+ *   })
+ * ```
+ *
+ * ## Learn more
+ * - {@apilink ErrorOptions}
+ * - {@apilink ErrorFactory}
+ * - {@apilink AssertionError}
+ * - {@apilink ConfigurationError}
+ * - {@apilink LogicError}
+ * - {@apilink RuntimeError}
+ * - {@apilink TestCompromisedError}
+ *
+ * @group Errors
+ */
+export declare class RaiseErrors extends Ability {
+    private readonly stage;
+    constructor(stage: Stage);
+    create<RE extends RuntimeError>(errorType: new (...args: any[]) => RE, options: ErrorOptions): RE;
+}
+//# sourceMappingURL=RaiseErrors.d.ts.map

package/lib/errors/RaiseErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RaiseErrors.d.ts","sourceRoot":"","sources":["../../src/errors/RaiseErrors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,WAAY,SAAQ,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,KAAK;IAIzC,MAAM,CAAC,EAAE,SAAS,YAAY,EAAE,SAAS,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,EAAE;CAGpG"}

package/lib/errors/RaiseErrors.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RaiseErrors = void 0;
+const screenplay_1 = require("../screenplay");
+/**
+ * An {@apilink Ability} that enables an {@apilink Actor} to create a Serenity/JS {@apilink RuntimeError}
+ * from within a custom {@apilink Interaction}.
+ *
+ * The stack trace of an error created this way includes the filesystem location pointing to where the interaction was invoked,
+ * which makes debugging any failures easier.
+ *
+ * :::info Pro tip
+ * The ability to `RaiseErrors` is given to all Serenity/JS actors by default, so you don't need to configure it explicitly.
+ * :::
+ *
+ * ## Raising an error
+ *
+ * ```typescript
+ * import { Interaction, LogicError, RaiseErrors } from '@serenity-js/core'
+ * import isPathInside from 'is-path-inside'
+ * import { unlink } from 'fs/promises'
+ *
+ * const RemoveFile = (pathToFile: string) =>
+ *   Interaction.where(`#actor removes a file at ${ pathToFile }`, async actor => {
+ *
+ *     if (! isPathInside(pathToFile, process.cwd())) {
+ *
+ *       throw RaiseErrors.as(actor).create(LogicError, {
+ *         message: `Removing files outside the current working directory is not allowed`
+ *         diff: {
+ *           expected: process.cwd(),
+ *           actual: pathToFile,
+ *         }
+ *       })
+ *     }
+ *
+ *     await unlink(pathToFile);
+ *   })
+ * ```
+ *
+ * ## Learn more
+ * - {@apilink ErrorOptions}
+ * - {@apilink ErrorFactory}
+ * - {@apilink AssertionError}
+ * - {@apilink ConfigurationError}
+ * - {@apilink LogicError}
+ * - {@apilink RuntimeError}
+ * - {@apilink TestCompromisedError}
+ *
+ * @group Errors
+ */
+class RaiseErrors extends screenplay_1.Ability {
+    constructor(stage) {
+        super();
+        this.stage = stage;
+    }
+    create(errorType, options) {
+        return this.stage.createError(errorType, options);
+    }
+}
+exports.RaiseErrors = RaiseErrors;
+//# sourceMappingURL=RaiseErrors.js.map

package/lib/errors/RaiseErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RaiseErrors.js","sourceRoot":"","sources":["../../src/errors/RaiseErrors.ts"],"names":[],"mappings":";;;AAAA,8CAAwC;AAKxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAa,WAAY,SAAQ,oBAAO;IACpC,YAA6B,KAAY;QACrC,KAAK,EAAE,CAAC;QADiB,UAAK,GAAL,KAAK,CAAO;IAEzC,CAAC;IAED,MAAM,CAA0B,SAAqC,EAAE,OAAqB;QACxF,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;CACJ;AARD,kCAQC"}

package/lib/errors/diff/AnsiDiffFormatter.d.ts

@@ -0,0 +1,28 @@
+import { Options } from 'chalk';
+import { DiffFormatter } from './DiffFormatter';
+/**
+ * A {@apilink DiffFormatter} that uses [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code)
+ * to format the output.
+ *
+ * @group Errors
+ */
+export declare class AnsiDiffFormatter implements DiffFormatter {
+    private readonly chalk;
+    /**
+     * Instantiates an `AnsiDiffFormatter`, configured with colour support options for [Chalk](https://github.com/chalk/chalk).
+     * When no `chalkOptions` object is provided, Chalk will auto-detect colour support automatically based on the execution environment.
+     *
+     * Available colour support levels:
+     * - `0` - All colours disabled.
+     * - `1` - Basic 16 colours support.
+     * - `2` - ANSI 256 colours support.
+     * - `3` - Truecolor - 16 million colours support.
+     *
+     * @param chalkOptions
+     */
+    constructor(chalkOptions?: Options);
+    expected(line: string): string;
+    received(line: string): string;
+    unchanged(line: string): string;
+}
+//# sourceMappingURL=AnsiDiffFormatter.d.ts.map

package/lib/errors/diff/AnsiDiffFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnsiDiffFormatter.d.ts","sourceRoot":"","sources":["../../../src/errors/diff/AnsiDiffFormatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,OAAO,EAAE,MAAM,OAAO,CAAC;AAElE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAE9B;;;;;;;;;;;OAWG;gBACS,YAAY,CAAC,EAAE,OAAO;IAIlC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI9B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI9B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAGlC"}