@plugjs/expect5 0.4.0

package/src/expectation/print.ts

@@ -0,0 +1,386 @@
+import { $grn, $gry, $red, $und, $wht, $ylw } from '@plugjs/plug/logging'
+import { textDiff } from '@plugjs/plug/utils'
+
+import { stringifyValue } from './types'
+
+import type { Diff, ExtraValueDiff, MissingValueDiff, ObjectDiff, ExpectedDiff } from './diff'
+import type { Logger } from '@plugjs/plug/logging'
+
+/* ========================================================================== *
+ * CONSTANT LABELS FOR PRINTING                                               *
+ * ========================================================================== */
+
+const _opnPar = $gry('(')
+const _clsPar = $gry(')')
+
+const _opnCrl = $gry('{')
+const _clsCrl = $gry('}')
+const _curls = $gry('{}')
+
+const _opnSqr = $gry('[')
+const _clsSqr = $gry(']')
+const _squares = $gry('[]')
+
+const _slash = $gry('/')
+const _tilde = $gry('~')
+const _hellip = $gry('\u2026')
+
+const _error = `${_opnPar}${$gry($und('error'))}${_clsPar}`
+const _string = `${_opnPar}${$gry($und('string'))}${_clsPar}`
+const _extraProps = $gry('\u2026 extra props \u2026')
+const _diffHeader = `${$wht('Differences')} ${_opnPar}${$red('actual')}${_slash}${$grn('expected')}${_slash}${$ylw('errors')}${_clsPar}:`
+
+/* ========================================================================== *
+ * PRINT DEPENDING ON DIFF TYPE                                               *
+ * ========================================================================== */
+
+function printBaseDiff(
+    log: Logger,
+    diff: Diff,
+    prop: string,
+    mapping: boolean,
+    comma: boolean,
+): void {
+  if ('props' in diff) return printObjectDiff(log, diff, prop, mapping, comma)
+  if ('values' in diff) return printObjectDiff(log, diff, prop, mapping, comma)
+  if ('mappings' in diff) return printObjectDiff(log, diff, prop, mapping, comma)
+  if ('expected' in diff) return printExpectedDiff(log, diff, prop, mapping, comma)
+  if ('missing' in diff) return printMissingDiff(log, diff, prop, mapping, comma)
+  if ('extra' in diff) return printExtraDiff(log, diff, prop, mapping, comma)
+
+  const { prefix, suffix } =
+      diff.error ? // default style if error is the only property
+          fixups(prop, mapping, comma, diff.error) :
+      diff.diff ? // label as "differs" if no error was found
+          fixups(prop, mapping, comma, diff.error, $red, 'differs') :
+      fixups(prop, mapping, comma, diff.error)
+
+  dump(log, diff.value, prefix, suffix, diff.diff ? $red : $wht)
+}
+
+/* ========================================================================== */
+
+function printExpectedDiff(
+    log: Logger,
+    diff: ExpectedDiff,
+    prop: string,
+    mapping: boolean,
+    comma: boolean,
+): void {
+  // two different strings get a special treatment: a proper "diff"
+  if ((typeof diff.value === 'string') && (typeof diff.expected === 'string')) {
+    const { prefix, suffix } = fixups(prop, mapping, false, diff.error)
+
+    log.warn(`${prefix}${_string}${suffix}`)
+    textDiff(diff.value, diff.expected).split('\n').forEach((line) => {
+      log.warn(`  ${_hellip} ${line}`)
+    })
+
+  // if "value" is not an object (can fit on one line) we use it as prefix
+  } else if ((diff.value === null) || (typeof diff.value !== 'object')) {
+    const { prefix, suffix } = fixups(prop, mapping, comma, diff.error)
+
+    const joined = `${prefix}${$red(stringify(diff.value))} ${_tilde} `
+    dump(log, diff.expected, joined, suffix, $grn)
+
+  // if "expected" is not an object (can fit on one line) we use it as suffix
+  } else if ((diff.expected === null) || (typeof diff.expected !== 'object')) {
+    const { prefix, suffix } = fixups(prop, mapping, comma, diff.error)
+
+    const joined = ` ${_tilde} ${$grn(stringify(diff.expected))}${suffix}`
+    dump(log, diff.value, prefix, joined, $red)
+
+  // both "value" and "expected" are objects, so, we join them with a ~
+  } else {
+    // here the error _only_ goes on the last line...
+    const { prefix, suffix: suffix1 } = fixups(prop, mapping, false, '')
+    const { suffix: suffix2 } = fixups(prop, mapping, comma, diff.error)
+
+    const lastLine = dumpAndContinue(log, diff.expected, prefix, suffix1, $red)
+    dump(log, diff.value, `${lastLine} ${_tilde} `, suffix2, $grn)
+  }
+}
+
+/* ========================================================================== */
+
+function printMissingDiff(
+    log: Logger,
+    diff: MissingValueDiff,
+    prop: string,
+    mapping: boolean,
+    comma: boolean,
+): void {
+  const { prefix, suffix } = fixups(prop, mapping, comma, diff.error, $red, 'missing')
+  dump(log, diff.missing, prefix, suffix, $red)
+}
+
+/* ========================================================================== */
+
+function printExtraDiff(
+    log: Logger,
+    diff: ExtraValueDiff,
+    prop: string,
+    mapping: boolean,
+    comma: boolean,
+): void {
+  const { prefix, suffix } = fixups(prop, mapping, comma, diff.error, $red, 'extra')
+  dump(log, diff.extra, prefix, suffix, $red)
+}
+
+/* ========================================================================== */
+
+function printObjectDiff(
+    log: Logger,
+    diff: ObjectDiff,
+    prop: string,
+    mapping: boolean,
+    comma: boolean,
+): void {
+  const { prefix, suffix } = fixups(prop, mapping, comma, diff.error)
+
+  // prepare for deep inspection
+  const value = diff.value
+  const ctor = Object.getPrototypeOf(value)?.constructor
+  const string = (ctor === Object) || (ctor === Array) ? '' : stringifyValue(value)
+
+  // prepare first line of output
+  let line = string ? `${prefix}${$wht(string)} ` : prefix
+  let marked = false
+
+  // arrays or sets
+  if (diff.values) {
+    if (diff.values.length === 0) {
+      line = `${line}${_squares}`
+    } else {
+      log.warn(`${line}${_opnSqr}`)
+      log.enter()
+      try {
+        for (const subdiff of diff.values) {
+          printBaseDiff(log, subdiff, '', false, true)
+        }
+      } finally {
+        log.leave()
+      }
+      line = _clsSqr
+    }
+    marked = true
+
+  // values and mappings (arrays/sets and maps) are mutually exclusive
+  } else if (diff.mappings) {
+    if (Object.keys(diff.mappings).length === 0) {
+      line = `${line}${_curls}`
+    } else {
+      log.warn(`${line}${_opnCrl}`)
+      log.enter()
+      try {
+        for (const [ key, subdiff ] of diff.mappings) {
+          printBaseDiff(log, subdiff, stringifyValue(key), true, true)
+        }
+      } finally {
+        log.leave()
+      }
+      line = _clsCrl
+    }
+    marked = true
+  }
+
+  // extra properties
+  if (diff.props) {
+    if (marked) line = `${line} ${_extraProps} `
+    if (Object.keys(diff.props).length === 0) {
+      line = `${line}${_curls}`
+    } else {
+      log.warn(`${line}${_opnCrl}`)
+      log.enter()
+      try {
+        for (const [ prop, subdiff ] of Object.entries(diff.props)) {
+          printBaseDiff(log, subdiff, stringifyValue(prop), false, true)
+        }
+      } finally {
+        log.leave()
+      }
+      line = _clsCrl
+    }
+    marked = true
+  }
+
+  log.warn(`${line}${suffix}`)
+}
+
+/* ========================================================================== *
+ * PRINT HELPERS                                                              *
+ * ========================================================================== */
+
+function stringify(
+    value: null | undefined | string | number | boolean | bigint | symbol | Function,
+): string {
+  if (typeof value === 'string') return JSON.stringify(value)
+  return stringifyValue(value)
+}
+
+function fixups(
+    prop: string,
+    mapping: boolean,
+    comma: boolean,
+    error: string | undefined,
+    color?: ((string: string) => string) | undefined,
+    label?: string,
+): { prefix: string, suffix: string } {
+  if (error) color = color || $ylw
+
+  const lbl = label ? `${_opnPar}${$gry($und(label))}${_clsPar} ` : ''
+  const sep = mapping ? ' => ': ': '
+  const prefix = prop ?
+      color ?
+          `${$gry(lbl)}${color(prop)}${$gry(sep)}` :
+          `${$gry(lbl)}${prop}${$gry(sep)}` :
+      label ?
+          `${$gry(lbl)}` :
+          ''
+  error = error ? ` ${_error} ${$ylw(error)}` : ''
+  const suffix = `${comma ? $gry(',') : ''}${error}`
+  return { prefix, suffix }
+}
+
+function dump(
+    log: Logger,
+    value: any,
+    prefix: string,
+    suffix: string,
+    color: (string: string) => string,
+    stack: any[] = [],
+): void {
+  log.warn(dumpAndContinue(log, value, prefix, suffix, color, stack))
+}
+
+function dumpAndContinue(
+    log: Logger,
+    value: any,
+    prefix: string,
+    suffix: string,
+    color: (string: string) => string,
+    stack: any[] = [],
+): string {
+  // primitives just get dumped
+  if ((value === null) || (typeof value !== 'object')) {
+    return `${prefix}${color(stringify(value))}${suffix}`
+  }
+
+  // check for circular dependencies
+  const circular = stack.indexOf(value)
+  if (circular >= 0) {
+    return `${prefix}${$gry($und(`<circular ${circular}>`))}${suffix}`
+  }
+
+  // prepare for deep inspection
+  const ctor = Object.getPrototypeOf(value)?.constructor
+  const string = (ctor === Object) || (ctor === Array) ? '' : stringifyValue(value)
+  const keys = new Set(Object.keys(value))
+
+  // prepare first line of output
+  let line = string ? `${prefix}${$wht(string)} ` : prefix
+  let marked = false
+
+  // arrays (will remove keys for properties)
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      line = `${line}${_squares}`
+    } else {
+      log.warn(`${line}${_opnSqr}`)
+      log.enter()
+      try {
+        for (let i = 0; i < value.length; i ++) {
+          const { prefix, suffix } = fixups('', false, true, undefined, color)
+          dump(log, value[i], prefix, suffix, color, [ ...stack, value ])
+          keys.delete(String(i))
+        }
+      } finally {
+        log.leave()
+      }
+      line = _clsSqr
+    }
+    marked = true
+
+    // arrays, sets and maps are mutually exclusive...
+  } else if (value instanceof Set) {
+    if (value.size === 0) {
+      line = `${line}${_squares}`
+    } else {
+      log.warn(`${line}${_opnSqr}`)
+      log.enter()
+      try {
+        const { prefix, suffix } = fixups('', false, true, undefined, color)
+        value.forEach((v) => dump(log, v, prefix, suffix, color, [ ...stack, value ]))
+      } finally {
+        log.leave()
+      }
+      line = _clsSqr
+    }
+    marked = true
+
+    // arrays, sets and maps are mutually exclusive...
+  } else if (value instanceof Map) {
+    if (value.size === 0) {
+      line = `${line}${_curls}`
+    } else {
+      log.warn(`${line}${_opnCrl}`)
+      log.enter()
+      try {
+        for (const [ key, subvalue ] of value) {
+          const { prefix, suffix } = fixups(stringifyValue(key), true, true, undefined, color)
+          dump(log, subvalue, prefix, suffix, color, [ ...stack, value ])
+        }
+      } finally {
+        log.leave()
+      }
+      line = _clsCrl
+    }
+    marked = true
+  }
+
+  // boxed strings leave props around
+  if (value instanceof String) {
+    const length = value.valueOf().length
+    for (let i = 0; i < length; i ++) keys.delete(String(i))
+  }
+
+  // extra properties might appear at any time...
+  if (keys.size) {
+    if (marked) line = `${line} ${_extraProps} `
+    log.warn(`${line}${_opnCrl}`)
+    log.enter()
+    try {
+      for (const key of keys) {
+        const { prefix, suffix } = fixups(stringifyValue(key), false, true, undefined, color)
+        dump(log, value[key], prefix, suffix, color, [ ...stack, value ])
+      }
+    } finally {
+      log.leave()
+    }
+    line = _clsCrl
+    marked = true
+  }
+
+  if (marked) {
+    return `${line}${suffix}`
+  } else {
+    return `${line}${_curls}${suffix}`
+  }
+}
+
+/* ========================================================================== *
+ * EXPORTSD                                                                   *
+ * ========================================================================== */
+
+/** Print a {@link Diff} to a log, with a nice header by default... */
+export function printDiff(log: Logger, diff: Diff, header = true): void {
+  if (! header) return printBaseDiff(log, diff, '', false, false)
+
+  log.warn(_diffHeader)
+  log.enter()
+  try {
+    printBaseDiff(log, diff, '', false, false)
+  } finally {
+    log.leave()
+  }
+}

package/src/expectation/throwing.ts

@@ -0,0 +1,45 @@
+import { ExpectationError, assertType } from './types'
+
+import type { Expectation, Expectations } from './expect'
+import type { Constructor, StringMatcher } from './types'
+
+export class ToThrow implements Expectation {
+  expect(
+      context: Expectations,
+      negative: boolean,
+      assert?: (errorExpectations: Expectations) => void,
+  ): void {
+    assertType(context, 'function')
+
+    let thrown: boolean
+    let error: unknown
+    try {
+      context.value()
+      thrown = false
+      error = undefined
+    } catch (caught) {
+      thrown = true
+      error = caught
+    }
+
+    if (thrown === negative) {
+      throw new ExpectationError(context, negative, 'to throw')
+    } else if (thrown && assert) {
+      assert(context.forValue(error))
+    }
+  }
+}
+
+export class ToThrowError implements Expectation {
+  expect(
+      context: Expectations,
+      negative: boolean,
+      ...args:
+      | []
+      | [ message: StringMatcher ]
+      | [ constructor: Constructor<Error> ]
+      | [ constructor: Constructor<Error>, message: StringMatcher ]
+  ): void {
+    context.negated(negative).toThrow((assert) => assert.toBeError(...args))
+  }
+}

package/src/expectation/types.ts

@@ -0,0 +1,263 @@
+import type { Diff } from './diff'
+import type { Expectations, ExpectationsMatcher } from './expect'
+
+/** A type identifying any constructor */
+export type Constructor<T = any> = new (...args: any[]) => T
+
+/** A type identifying any function */
+export type Callable<T = any> = (...args: readonly any[]) => T
+
+/** A simple _record_ indicating an `object` but never an `array` */
+export type NonArrayObject<T = any> = {
+  [a: string]: T
+  [b: symbol]: T
+  [c: number]: never
+}
+
+/** A type identifying the parameter of `string.match(...)` */
+export type StringMatcher = string | RegExp | {
+  [Symbol.match](string: string): RegExpMatchArray | null
+}
+
+/** Mappings for our _expanded_ {@link typeOf} implementation */
+export type TypeMappings = {
+  // standard types, from "typeof"
+  bigint: bigint,
+  boolean: boolean,
+  function: Callable,
+  number: number,
+  string: string,
+  symbol: symbol,
+  undefined: undefined,
+  // specialized object types
+  array: readonly any [],
+  buffer: Buffer,
+  map: Map<any, any>,
+  promise: PromiseLike<any>,
+  regexp: RegExp,
+  set: Set<any>,
+  // object: anything not mapped above, not null, and not an array
+  object: NonArrayObject<any>,
+  // oh, javascript :-(
+  null: null,
+}
+
+/** Values returned by our own _expanded_ `{@link typeOf}` */
+export type TypeName = keyof TypeMappings
+
+/* ========================================================================== *
+ * TYPE INSPECTION, GUARD, AND ASSERTION                                      *
+ * ========================================================================== */
+
+/** Expanded `typeof` implementation returning some extra types */
+export function typeOf(value: unknown): TypeName {
+  if (value === null) return 'null' // oh, javascript :-(
+
+  // primitive types
+  const type = typeof value
+  switch (type) {
+    case 'bigint':
+    case 'boolean':
+    case 'function':
+    case 'number':
+    case 'string':
+    case 'symbol':
+    case 'undefined':
+      return type
+  }
+
+  // extended types
+  if (Array.isArray(value)) return 'array'
+
+  if (value instanceof Promise) return 'promise'
+  if (typeof (value as any)['then'] === 'function') return 'promise'
+
+  if (value instanceof Buffer) return 'buffer'
+  if (value instanceof RegExp) return 'regexp'
+  if (value instanceof Map) return 'map'
+  if (value instanceof Set) return 'set'
+
+  // anything else is an object
+  return 'object'
+}
+
+/** Determines if the specified `value` is of the specified _expanded_ `type` */
+export function isType<T extends keyof TypeMappings>(
+    context: Expectations,
+    type: T,
+): context is Expectations<TypeMappings[T]> {
+  return typeOf(context.value) === type
+}
+
+/** Asserts that the specified `value` is of the specified _expanded_ `type` */
+export function assertType<T extends keyof TypeMappings>(
+    context: Expectations,
+    type: T,
+): asserts context is Expectations<TypeMappings[T]> {
+  const { value } = context
+
+  if (typeOf(value) === type) return
+
+  throw new ExpectationError(context, false, `to be ${prefixType(type)}`)
+}
+
+/* ========================================================================== *
+ * PRETTY PRINTING FOR MESSAGES AND DIFFS                                     *
+ * ========================================================================== */
+
+/** Get constructor name or default for {@link stringifyValue} */
+function constructorName(value: Record<any, any>): string {
+  return Object.getPrototypeOf(value)?.constructor?.name
+}
+
+/** Format binary data for {@link stringifyValue} */
+function formatBinaryData(value: Record<any, any>, buffer: Buffer): string {
+  const binary = buffer.length > 20 ?
+      `${buffer.toString('hex', 0, 20)}\u2026, length=${value.length}` :
+      buffer.toString('hex')
+  return binary ?
+      `[${constructorName(value)}: ${binary}]` :
+      `[${constructorName(value)}: empty]`
+}
+
+/* ========================================================================== */
+
+/** Stringify the type of an object (its constructor name) */
+export function stringifyObjectType(value: object): string {
+  const proto = Object.getPrototypeOf(value)
+  if (! proto) return '[Object: null prototype]'
+  return stringifyConstructor(proto.constructor)
+}
+
+/** Stringify a constructor */
+export function stringifyConstructor(ctor: Constructor): string {
+  if (! ctor) return '[Object: no constructor]'
+  if (! ctor.name) return '[Object: anonymous]'
+  return `[${ctor.name}]`
+}
+
+/** Pretty print the value (strings, numbers, booleans) or return the type */
+export function stringifyValue(value: unknown): string {
+  if (value === null) return '<null>'
+  if (value === undefined) return '<undefined>'
+
+  switch (typeof value) {
+    case 'string':
+      if (value.length > 40) value = `${value.substring(0, 40)}\u2026, length=${value.length}`
+      return JSON.stringify(value)
+    case 'number':
+      if (value === Number.POSITIVE_INFINITY) return '+Infinity'
+      if (value === Number.NEGATIVE_INFINITY) return '-Infinity'
+      return String(value)
+    case 'boolean':
+      return String(value)
+    case 'bigint':
+      return `${value}n`
+    case 'function':
+      return value.name ? `<function ${value.name}>` : '<function>'
+    case 'symbol':
+      return value.description ? `<symbol ${value.description}>`: '<symbol>'
+  }
+
+  // specific object types
+  if (isMatcher(value)) return '<matcher>'
+  if (value instanceof RegExp) return String(value)
+  if (value instanceof Date) return `[${constructorName(value)}: ${value.toISOString()}]`
+  if (value instanceof Boolean) return `[${constructorName(value)}: ${value.valueOf()}]`
+  if (value instanceof Number) return `[${constructorName(value)}: ${stringifyValue(value.valueOf())}]`
+  if (value instanceof String) return `[${constructorName(value)}: ${stringifyValue(value.valueOf())}]`
+
+  if (Array.isArray(value)) return `[${constructorName(value)} (${value.length})]`
+  if (value instanceof Set) return `[${constructorName(value)} (${value.size})]`
+  if (value instanceof Map) return `[${constructorName(value)} (${value.size})]`
+
+  if (value instanceof Buffer) return formatBinaryData(value, value)
+  if (value instanceof Uint8Array) return formatBinaryData(value, Buffer.from(value))
+  if (value instanceof ArrayBuffer) return formatBinaryData(value, Buffer.from(value))
+  if (value instanceof SharedArrayBuffer) return formatBinaryData(value, Buffer.from(value))
+
+  // inspect anything else...
+  return stringifyObjectType(value)
+}
+
+/** Add the `a`/`an`/... prefix to the type name */
+export function prefixType(type: TypeName): string {
+  switch (type) {
+    case 'bigint':
+    case 'boolean':
+    case 'buffer':
+    case 'function':
+    case 'map':
+    case 'number':
+    case 'promise':
+    case 'regexp':
+    case 'set':
+    case 'string':
+    case 'symbol':
+      return `a <${type}>`
+
+    case 'array':
+    case 'object':
+      return `an <${type}>`
+
+    case 'null':
+    case 'undefined':
+      return `<${type}>`
+
+    default:
+      return `of unknown type <${type}>`
+  }
+}
+
+/* ========================================================================== *
+ * EXPECTATIONS MATCHERS MARKER                                               *
+ * ========================================================================== */
+
+export const matcherMarker = Symbol.for('expect5.matcher')
+
+export function isMatcher(what: any): what is ExpectationsMatcher {
+  return what && what[matcherMarker] === matcherMarker
+}
+
+/* ========================================================================== *
+ * EXPECTATION ERRORS                                                         *
+ * ========================================================================== */
+
+export class ExpectationError extends Error {
+  diff?: Diff | undefined
+
+  constructor(
+      context: Expectations,
+      negative: boolean,
+      details: string,
+      diff?: Diff,
+  ) {
+    const { value } = context
+    const not = negative ? ' not' : ''
+
+    // if we're not root...
+    let preamble = stringifyValue(value)
+    if (context.parent) {
+      const properties: any[] = []
+
+      while (context.parent) {
+        properties.push(`[${stringifyValue(context.parent.prop)}]`)
+        context = context.parent.context
+      }
+
+      preamble = properties.reverse().join('')
+
+      // type of root value is constructor without details
+      const type = typeof context.value === 'object' ?
+          stringifyObjectType(context.value as object) : // parent values can not be null!
+          stringifyValue(context.value)
+
+      // assemble the preamble
+      preamble = `property ${preamble} of ${type} (${stringifyValue(value)})`
+    }
+
+    super(`Expected ${preamble}${not} ${details}`)
+
+    if (diff) this.diff = diff
+  }
+}