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

package/src/io/inspected.ts

@@ -1,272 +1,14 @@
-import { inspect } from 'util';
-
-import { Answerable } from '../screenplay/Answerable';
-import { Question } from '../screenplay/Question';
-
-interface InspectedConfig {
-    inline: boolean;
-    markQuestions?: boolean;
-}
-
-/**
- * @desc
- *  Provides a human-readable description of the {@link Answerable<T>}.
- *  Similar to {@link util~inspect}.
- *
- * @public
- * @param {Answerable<any>} value
- * @param config
- *  - inline - Return a single-line string instead of the default potentially multi-line description
- *  - markQuestions - Surround the description of async values, such as Promises and Questions with <<value>>
- * @return {string}
- */
-export function inspected(value: Answerable<any>, config?: InspectedConfig): string {
-
-    const { inline, markQuestions } = { inline: false, markQuestions: false, ...config };
-
-    if (! isDefined(value)) {
-        return inspect(value);
-    }
-
-    if (Array.isArray(value)) {
-        return stringifiedArray(value, inline);
-    }
-
-    if (isAPromise(value)) {
-        return markAs('Promise', true);
-    }
-
-    if (Question.isAQuestion(value)) {
-        return markAs(value.toString(), markQuestions);
-    }
-
-    if (isADate(value)) {
-        return value.toISOString();
-    }
-
-    if (hasItsOwnToString(value)) {
-        return value.toString();
-    }
-
-    if (isInspectable(value)) {
-        return value.inspect();
-    }
-
-    if (isAFunction(value)) {
-        return hasName(value)
-            ? value.name
-            : markAs(`Function`, true);
-    }
-
-    if (! hasCustomInspectionFunction(value) && isPlainObject(value) && isSerialisableAsJSON(value)) {
-        return stringifiedToJson(value, inline);
-    }
-
-    return inspect(value, { breakLength: Number.POSITIVE_INFINITY, compact: inline ? 3 : false, sorted: false  });
-}
-
-function stringifiedToJson(value: any, inline: boolean): string {
-    const indentation = inline ? 0 : 4;
-
-    return JSON.stringify(value, undefined, indentation);
-}
-
-function stringifiedArray(value: any[], inline: boolean): string {
-    const indentation   = inline ? '' : '  ';
-    const separator     = inline ? ' ' : '\n';
-
-    const inspectedItem = (item: unknown, index: number) =>
-        [
-            indentation,
-            inspected(item, { inline, markQuestions: true }),
-            index < value.length - 1 ? ',' : ''
-        ].join('')
-
-    return [
-        '[',
-        ...value.map(inspectedItem),
-        ']',
-    ].join(separator);
-}
-
-function markAs(value: string, markValue: boolean): string {
-    const [left, right] = markValue && ! value.startsWith('<<')
-        ? [ '<<', '>>' ]
-        : ['', ''];
-
-    return [ left, value, right ].join('');
-}
-
-/**
- * @desc
- * Checks if the value is defined
- *
- * @private
- * @param {Answerable<any>} v
- */
-function isDefined(v: Answerable<any>) {
-    return !! v;
-}
-
-/**
- * @desc
- * Checks if the value defines its own `toString` method
- *
- * @private
- * @param {Answerable<any>} v
- */
-function hasItsOwnToString(v: Answerable<any>): v is { toString: () => string } {
-    return typeof v === 'object'
-        && !! (v as any).toString
-        && typeof (v as any).toString === 'function'
-        && ! isNative((v as any).toString);
-}
-
-/**
- * @desc
- * Checks if the value defines its own `inspect` method
- *
- * @private
- * @param {Answerable<any>} v
- */
-function isInspectable(v: Answerable<any>): v is { inspect: () => string } {
-    return !! (v as any).inspect && typeof (v as any).inspect === 'function';
-}
-
-/**
- * @desc
- * Checks if the value is a {@link Date}
- *
- * @private
- * @param {Answerable<any>} v
- */
-function isADate(v: Answerable<any>): v is Date {
-    return v instanceof Date;
-}
-
-/**
- * @desc
- * Checks if the value is a {@link Promise}
- *
- * @private
- * @param {Answerable<any>} v
- */
-function isAPromise<T>(v: Answerable<T>): v is Promise<T> {
-    return typeof v === 'object'
-        && 'then' in v;
-}
-
-/**
- * @desc
- * Checks if the value is a named {@link Function}
- *
- * @private
- * @param {Answerable<any>} v
- */
-function isAFunction(v: any): v is Function {       // eslint-disable-line @typescript-eslint/ban-types
-    return Object.prototype.toString.call(v) === '[object Function]';
-}
-
-/**
- * @desc
- *  Checks if the value is has a property called 'name' with a non-empty value.
- *
- * @private
- * @param {Answerable<any>} v
- */
-function hasName(v: any): v is { name: string } {
-    return typeof (v as any).name === 'string' && (v as any).name !== '';
-}
-
-/**
- * @desc
- * Checks if the value defines its own `inspect` method
- * See: https://nodejs.org/api/util.html#util_util_inspect_custom
- *
- * @private
- * @param {Answerable<any>} v
- */
-function hasCustomInspectionFunction(v: Answerable<any>): v is object { // eslint-disable-line @typescript-eslint/ban-types
-    return v && v[Symbol.for('nodejs.util.inspect.custom')];
-}
-
-/**
- * @desc
- * Checks if the value has a good chance of being a plain JavaScript object
- *
- * @private
- * @param {Answerable<any>} v
- */
-function isPlainObject(v: Answerable<any>): v is object {   // eslint-disable-line @typescript-eslint/ban-types
-
-    // Basic check for Type object that's not null
-    if (typeof v === 'object' && v !== null) {
-
-        // If Object.getPrototypeOf supported, use it
-        if (typeof Object.getPrototypeOf === 'function') {
-            const proto = Object.getPrototypeOf(v);
-            return proto === Object.prototype || proto === null;
-        }
-
-        // Otherwise, use internal class
-        // This should be reliable as if getPrototypeOf not supported, is pre-ES5
-        return Object.prototype.toString.call(v) === '[object Object]';
-    }
-
-    // Not an object
-    return false;
-}
-
-/**
- * @desc
- * Checks if the value is a JSON object that can be stringified
- *
- * @private
- * @param {Answerable<any>} v
- */
-function isSerialisableAsJSON(v: any): v is object {    // eslint-disable-line @typescript-eslint/ban-types
-    try {
-        JSON.stringify(v);
-
-        return true;
-    } catch {
-        return false;
-    }
-}
-
-/**
- * https://davidwalsh.name/detect-native-function
- * @param {any} v
- */
-function isNative(v: any): v is Function {  // eslint-disable-line @typescript-eslint/ban-types
-
-    const
-        toString        = Object.prototype.toString,    // Used to resolve the internal `[[Class]]` of values
-        fnToString      = Function.prototype.toString,  // Used to resolve the decompiled source of functions
-        hostConstructor = /^\[object .+?Constructor]$/; // Used to detect host constructors (Safari > 4; really typed array specific)
-
-    // Compile a regexp using a common native method as a template.
-    // We chose `Object#toString` because there's a good chance it is not being mucked with.
-    const nativeFunctionTemplate = new RegExp(
-        '^' +
-        // Coerce `Object#toString` to a string
-        String(toString)
-        // Escape any special regexp characters
-            .replace(/[$()*+./?[\\\]^{|}]/g , '\\$&')
-            // Replace mentions of `toString` with `.*?` to keep the template generic.
-            // Replace thing like `for ...` to support environments like Rhino which add extra info
-            // such as method arity.
-            .replace(/toString|(function).*?(?=\\\()| for .+?(?=\\])/g, '$1.*?') +
-        '$',
-    );
-
-    const type = typeof v;
-    return type === 'function'
-        // Use `Function#toString` to bypass the value's own `toString` method
-        // and avoid being faked out.
-        ? nativeFunctionTemplate.test(fnToString.call(v))
-        // Fallback to a host object check because some environments will represent
-        // things like typed arrays as DOM methods which may not conform to the
-        // normal native pattern.
-        : (v && type === 'object' && hostConstructor.test(toString.call(v))) || false;
+import { inspect, InspectOptions } from 'util';
+
+export function inspected(value: unknown, options: InspectOptions = {}): string {
+    return inspect(value, {
+        depth: Number.POSITIVE_INFINITY,
+        breakLength: Number.POSITIVE_INFINITY,
+        customInspect: true,
+        compact:  false,
+        sorted: true,
+        showProxy: false,
+        showHidden: false,
+        ...options,
+    });
 }

package/src/io/inspectedObject.ts

@@ -0,0 +1,38 @@
+import * as util from 'util'; // eslint-disable-line unicorn/import-style
+
+import { typeOf } from './reflection';
+
+export function inspectedObject<T>(value: T, allowFields?: Array<keyof T>): (depth: number, options: util.InspectOptionsStylized, inspect: typeof util.inspect) => string {
+    return function (depth: number, options: util.InspectOptionsStylized, inspect: typeof util.inspect = util.inspect): string {
+        const typeName = options.stylize(typeOf(value), 'special');
+
+        if (depth < 0) {
+            return typeName;
+        }
+
+        const fields = Object.getOwnPropertyNames(value)
+            .filter(field => typeof value[field] !== 'function')
+            .filter(field => allowFields ? allowFields.includes(field as keyof T) : true)
+            .sort();
+
+        if (fields.length === 0) {
+            return `${ typeName } { }`;
+        }
+
+        const newOptions = Object.assign({}, options, {
+            depth: options?.depth > 0
+                ? options.depth - 1
+                : undefined,
+        });
+
+        const padding = ' '.repeat(2);
+
+        const lines = fields.flatMap(
+            field => `${ field }: ${ inspect(value[field], newOptions) }`
+                .split('\n')
+                .map(line => `${ padding }${ line }`)
+        ).join('\n');
+
+        return `${ typeName } {\n${ lines }\n}`;
+    }
+}

package/src/io/loader/ClassDescriptionParser.ts

@@ -0,0 +1,67 @@
+import validate from 'validate-npm-package-name';
+
+import { ClassDescription } from '../../config';
+import { ConfigurationError } from '../../errors';
+import { d } from '../format';
+import { ClassDescriptor } from './ClassDescriptor';
+
+export class ClassDescriptionParser {
+    private static validClassNamePattern = /^[A-Za-z]\w+$/;
+
+    looksLikeClassDescription(candidate: unknown): candidate is ClassDescription {
+        const stringDescription = typeof candidate === 'string';
+        const tupleDescription  = Array.isArray(candidate) && [ 1, 2 ].includes(candidate.length) && typeof candidate[0] === 'string';
+
+        return stringDescription || tupleDescription;
+    }
+
+    parse(classDescription: ClassDescription): ClassDescriptor {
+        if (! this.looksLikeClassDescription(classDescription)) {
+            throw new ConfigurationError(d`${ classDescription } is not a valid class description. Valid class description must be a string or an Array with 1-2 items, where the first item is a string.`);
+        }
+
+        const moduleIdAndClassDescription = Array.isArray(classDescription)
+            ? classDescription[0]
+            : classDescription as string;
+
+        const [ moduleId, desiredClassName, ...rest ] = moduleIdAndClassDescription.split(':');
+
+        if (rest.length > 0) {
+            throw new ConfigurationError(
+                `${ classDescription } is not a valid class description. Valid class description must be:\n` +
+                `- a module ID of a Node module providing a default export, e.g. "@serenity-js/serenity-bdd"\n` +
+                `- a module ID followed by a class name, e.g. "@serenity-js/core:StreamReporter"`
+            );
+        }
+
+        if (desiredClassName === '') {
+            throw new ConfigurationError(
+                `Invalid class name in "${ moduleIdAndClassDescription }". If you want to import the default export from a given module, please use the module ID.\n` +
+                `For example, valid class descriptions include "@serenity-js/serenity-bdd", "@serenity-js/serenity-bdd:default", "@serenity-js/serenity-bdd:SerenityBDD".`
+            );
+        }
+
+        const className = desiredClassName ?? 'default';
+
+        if (! ClassDescriptionParser.validClassNamePattern.test(className)) {
+            throw new ConfigurationError(
+                `"${className}" doesn't seem like a valid JavaScript class name in "${ moduleIdAndClassDescription }"`
+            );
+        }
+
+        if (! moduleId.startsWith('./')) {
+            const result = validate(moduleId);
+            if (! result.validForNewPackages) {
+                throw new ConfigurationError(
+                    `"${ moduleId }" doesn't seem like a valid module id:\n${ result.errors.map(error => `- ${error}\n`) }`
+                );
+            }
+        }
+
+        return {
+            moduleId,
+            className,
+            parameter: Array.isArray(classDescription) ? classDescription[1] : undefined,
+        }
+    }
+}

package/src/io/loader/ClassDescriptor.ts

@@ -0,0 +1,7 @@
+import { JSONValue } from 'tiny-types';
+
+export interface ClassDescriptor {
+    moduleId: string;
+    className: string;
+    parameter: JSONValue;
+}

package/src/io/loader/ClassLoader.ts

@@ -0,0 +1,42 @@
+import { ClassDescription } from '../../config';
+import { ConfigurationError } from '../../errors';
+import { d } from '../format';
+import { ClassDescriptionParser } from './ClassDescriptionParser';
+import { ModuleLoader } from './ModuleLoader';
+
+export class ClassLoader {
+    constructor(
+        private readonly loader: ModuleLoader,
+        private readonly parser: ClassDescriptionParser,
+    ) {
+    }
+
+    looksLoadable(description: unknown): description is ClassDescription {
+        return this.parser.looksLikeClassDescription(description);
+    }
+
+    instantiate<T>(description: ClassDescription): T {
+        const descriptor = this.parser.parse(description);
+
+        const requiredModule    = this.loader.require(descriptor.moduleId);
+        const requiredType      = requiredModule[descriptor.className];
+
+        if (typeof requiredType !== 'function') {
+            throw new ConfigurationError(d `Module ${ descriptor.moduleId } doesn't seem to export ${ descriptor.className }. Exported members include: ${ Object.keys(requiredModule).join(', ') }`)
+        }
+
+        if (descriptor.parameter) {
+            if (typeof requiredType.fromJSON !== 'function') {
+                throw new ConfigurationError(d `Class ${ descriptor.className } exported by ${ descriptor.moduleId } needs a static fromJSON() method that accepts ${ descriptor.parameter }`);
+            }
+
+            return requiredType.fromJSON(descriptor.parameter);
+        }
+
+        if (requiredType.length > 0) {
+            throw new ConfigurationError(d`Class ${ descriptor.className } exported by ${ descriptor.moduleId } doesn't seem to offer a no-arg constructor`);
+        }
+
+        return new requiredType();
+    }
+}

package/src/io/{ModuleLoader.ts → loader/ModuleLoader.ts}

@@ -1,12 +1,11 @@
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const Module = require('module'); // No type definitions available
-import * as path from 'path';   // eslint-disable-line unicorn/import-style
+import * as path from 'path'; // eslint-disable-line unicorn/import-style
 
 import { Version } from './Version';
 
 /**
- * @desc
- *  Dynamically loads Node modules located relative to `cwd`.
+ * Dynamically loads Node modules located relative to `cwd`.
  */
 export class ModuleLoader {
 
@@ -18,10 +17,9 @@ export class ModuleLoader {
     }
 
     /**
-     * @desc
-     *  Returns true if a given module is available to be required, false otherwise.
+     * Returns `true` if a given module is available to be required, false otherwise.
      *
-     * @param {string} moduleId
+     * @param moduleId
      *  NPM module id, for example 'cucumber' or '@serenity-js/core'
      */
     hasAvailable(moduleId: string): boolean {
@@ -33,13 +31,12 @@ export class ModuleLoader {
     }
 
     /**
-     * @desc
-     *  Works like `require.resolve`, but relative to specified current working directory
+     * Works like `require.resolve`, but relative to specified current working directory
      *
-     * @param {string} moduleId
+     * @param moduleId
      *  NPM module id, for example `cucumber` or `@serenity-js/core`
      *
-     * @returns {string}
+     * @returns
      *  Path a given Node module
      */
     resolve(moduleId: string): string {
@@ -53,12 +50,9 @@ export class ModuleLoader {
     }
 
     /**
-     * @desc
-     *  Works like `require`, but relative to specified current working directory
+     * Works like `require`, but relative to specified current working directory
      *
-     * @param {string} moduleId
-     *
-     * @returns {any}
+     * @param moduleId
      */
     require(moduleId: string): any {
         try {
@@ -70,11 +64,9 @@ export class ModuleLoader {
     }
 
     /**
-     * @desc
-     *  Returns {@link Version} of module specified by `moduleId`, based on its `package.json`.
+     * Returns {@apilink Version} of module specified by `moduleId`, based on its `package.json`.
      *
-     * @param {string} moduleId
-     * @returns {Version}
+     * @param moduleId
      */
     versionOf(moduleId: string): Version {
         return new Version(this.require(`${ moduleId }/package.json`).version);

package/src/io/{Version.ts → loader/Version.ts}

@@ -1,11 +1,8 @@
-import semver = require('semver');
+import semver from 'semver';
 import { ensure, isDefined, isString, Predicate, TinyType } from 'tiny-types';
 
 /**
- * @desc
- *  A tiny type describing a version number, like `1.2.3`
- *
- * @extends {tiny-types~TinyType}
+ * A tiny type describing a version number, like `1.2.3`
  */
 export class Version extends TinyType {
 

package/src/io/loader/index.ts

@@ -0,0 +1,5 @@
+export * from './ClassDescriptionParser';
+export * from './ClassDescriptor';
+export * from './ClassLoader';
+export * from './ModuleLoader';
+export * from './Version';

package/src/io/reflection/has.ts

@@ -1,12 +1,11 @@
 /**
- * @desc
  *  Checks if the `candidate` value "quacks like a duck".
  *  In particular, it checks if the `candidate`:
  *  - is not `null`
  *  - is not `undefined`
  *  - has expected methods or fields (evaluated via [`typeof`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof))
  *
- * @example
+ * ```ts
  *  const looksLikeADuck = has({
  *      name:   'string',
  *      quack:  'function',
@@ -18,12 +17,11 @@
  *  }
  *
  *  looksLikeADuck(daisy) // true
+ * ```
  *
- * @param {object} api
+ * @param api
  *  An object where the keys are names of member fields and methods expected on the `candidate`,
  *  and values are the names of their types, i.e. `function`, `object`, etc.
- *
- * @returns {boolean}
  */
 export function has<T>(api: Record<keyof T, string>): (candidate: unknown) => candidate is T {
     return (candidate: unknown): candidate is T =>

package/src/io/reflection/index.ts

@@ -1 +1,3 @@
 export * from './has';
+export * from './isPrimitive';
+export * from './typeOf';

package/src/io/reflection/isPrimitive.ts

@@ -0,0 +1,20 @@
+/**
+ * Returns true if `value` is a [JavaScript primitive](https://developer.mozilla.org/en-US/docs/Glossary/Primitive),
+ * false otherwise.
+ *
+ * @param value
+ */
+export function isPrimitive(value: unknown): boolean {
+    if (value === null) {
+        return true;
+    }
+
+    return [
+        'string',
+        'number',
+        'bigint',
+        'boolean',
+        'undefined',
+        'symbol'
+    ].includes(typeof value);
+}

package/src/io/reflection/typeOf.ts

@@ -0,0 +1,31 @@
+import { types } from 'util';
+
+/**
+ * Describes the type of the provided value.
+ *
+ * @param value
+ */
+export function typeOf(value: unknown): string {
+    switch (true) {
+        case value === null:
+            return 'null';
+        case types.isProxy(value):
+            return `Proxy<${ Reflect.getPrototypeOf(value as object).constructor.name }>`;
+        case typeof value !== 'object':
+            return typeof value;
+        case value instanceof Date:
+            return `Date`;
+        case Array.isArray(value):
+            return `Array`;
+        case value instanceof RegExp:
+            return `RegExp`
+        case value instanceof Set:
+            return 'Set';
+        case value instanceof Map:
+            return 'Map';
+        case !! value.constructor && value.constructor !== Object:
+            return value.constructor.name
+        default:
+            return 'object';
+    }
+}