@plugjs/expect5 0.4.0

package/src/expectation/expect.ts

@@ -0,0 +1,401 @@
+import { ExpectationError, matcherMarker } from './types'
+import {
+  ToBeA,
+  ToBeCloseTo,
+  ToBeError,
+  ToBeGreaterThan,
+  ToBeGreaterThanOrEqual,
+  ToBeInstanceOf,
+  ToBeLessThan,
+  ToBeLessThanOrEqual,
+  ToBeWithinRange,
+  ToEqual,
+  ToHaveLength,
+  ToHaveProperty,
+  ToHaveSize,
+  ToMatch,
+  ToStrictlyEqual,
+} from './basic'
+import {
+  ToInclude, ToMatchContents,
+} from './include'
+import {
+  ToThrow,
+  ToThrowError,
+} from './throwing'
+import {
+  ToBeDefined,
+  ToBeFalse,
+  ToBeFalsy,
+  ToBeNaN,
+  ToBeNegativeInfinity,
+  ToBeNull,
+  ToBePositiveInfinity,
+  ToBeTrue,
+  ToBeTruthy,
+  ToBeUndefined,
+} from './void'
+
+import type { Constructor, StringMatcher } from './types'
+
+/* ========================================================================== *
+ * IMPORT AND PREPARE EXTERNAL EXPECTATIONS                                   *
+ * ========================================================================== */
+
+/** Singleton with all imported (known) expectations */
+const expectations = {
+  // basic expectations
+  toBeA: new ToBeA(),
+  toBeCloseTo: new ToBeCloseTo(),
+  toBeError: new ToBeError(),
+  toBeGreaterThan: new ToBeGreaterThan(),
+  toBeGreaterThanOrEqual: new ToBeGreaterThanOrEqual(),
+  toBeInstanceOf: new ToBeInstanceOf(),
+  toBeLessThan: new ToBeLessThan(),
+  toBeLessThanOrEqual: new ToBeLessThanOrEqual(),
+  toBeWithinRange: new ToBeWithinRange(),
+  toEqual: new ToEqual(),
+  toHaveLength: new ToHaveLength(),
+  toHaveProperty: new ToHaveProperty(),
+  toHaveSize: new ToHaveSize(),
+  toMatch: new ToMatch(),
+  toStrictlyEqual: new ToStrictlyEqual(),
+
+  // include
+  toInclude: new ToInclude(),
+  toMatchContents: new ToMatchContents(),
+
+  // throwing
+  toThrow: new ToThrow(),
+  toThrowError: new ToThrowError(),
+
+  // void expectations
+  toBeDefined: new ToBeDefined(),
+  toBeFalse: new ToBeFalse(),
+  toBeFalsy: new ToBeFalsy(),
+  toBeNaN: new ToBeNaN(),
+  toBeNegativeInfinity: new ToBeNegativeInfinity(),
+  toBeNull: new ToBeNull(),
+  toBePositiveInfinity: new ToBePositiveInfinity(),
+  toBeTrue: new ToBeTrue(),
+  toBeTruthy: new ToBeTruthy(),
+  toBeUndefined: new ToBeUndefined(),
+} as const
+
+/** The type of our imported expectations */
+type ExpectationsByName = typeof expectations
+
+/** Infer expectations parameter from {@link Expectation} type */
+type ExpectationParameters<E> =
+  E extends Expectation ?
+    Parameters<E['expect']> extends [ any, any, ...infer P ] ? P : never :
+  never
+
+/** Infer return parameter from {@link Expectation} type */
+type ExpectationReturn<E, T> = E extends Expectation ? Expectations<T> : never
+
+/** Infer expectation functions from imported {@link Expectation} instances */
+type ImportedExpectations<T = unknown> = {
+  [ k in keyof ExpectationsByName ]: (
+    ...args: ExpectationParameters<ExpectationsByName[k]>
+  ) => ExpectationReturn<ExpectationsByName[k], T>
+}
+
+/* ========================================================================== *
+ * EXPECTATIONS DEFINITION                                                    *
+ * ========================================================================== */
+
+/** An interface describing all expectations returned by `expect(...)` */
+export interface Expectations<T = unknown> extends ImportedExpectations<T> {
+  /**
+   * The parent of this instance, if and only if this is a child derived from
+   * a property of the parent instance's value.
+   */
+  parent?: ExpectationsParent
+
+  /** The value this {@link Expectations} instance operates on */
+  value: T
+
+  /** The _negated_ expectations of _this_ {@link Expectations} instance. */
+  not: Expectations<T>
+
+  /**
+   * Programmatically return _positive_ or _negative_ {@link Expectations}
+   * for the value wrapped by this instance.
+   */
+  negated(negative: boolean): Expectations<T>
+
+  /** Create an {@link Expectations} associated with a property of this value */
+  forProperty(prop: string | number | symbol): Expectations
+
+  /** Create a new {@link Expectations} instance for the specified value */
+  forValue<T = unknown>(value: T): Expectations<T>
+
+  /* == ASYNCHRONOUS EXPECTATIONS =========================================== */
+
+  /** Expect the value to be a _resolved_ {@link Promise} */
+  toBeResolved(): Promise<ExpectationsImpl<T>>
+  /**
+   * Expect the value to be a _resolved_ {@link Promise}, and assert the
+   * resolved result with the specified callback
+   */
+  toBeResolved(assert: (resultExpectations: Expectations) => void): Promise<ExpectationsImpl<T>>
+
+  /** Expect the value to be a _rejected_ {@link Promise} */
+  toBeRejected(): Promise<ExpectationsImpl<T>>
+  /**
+   * Expect the value to be a _rejected_ {@link Promise}, and assert the
+   * rejected reason with the specified callback
+   */
+  toBeRejected(assert?: (rejectionExpectations: Expectations) => void): Promise<ExpectationsImpl<T>>
+
+  /** Expect the value to be a {@link Promise} _rejected_ by an {@link Error} */
+  toBeRejectedWithError(): Promise<Expectations<T>>
+  /**
+   * Expect the value to be a {@link Promise} _rejected_ by an {@link Error}
+   * with the specified _message_
+   */
+  toBeRejectedWithError(message: StringMatcher): Promise<Expectations<T>>
+  /**
+   * Expect the value to be a {@link Promise} _rejected_ by an {@link Error}
+   * of the specified _type_
+   */
+  toBeRejectedWithError(constructor: Constructor<Error>): Promise<Expectations<T>>
+  /**
+   * Expect the value to be a {@link Promise} _rejected_ by an {@link Error}
+   * of the specified _type_ and with the specified _message_
+   */
+  toBeRejectedWithError(constructor: Constructor<Error>, message: StringMatcher): Promise<Expectations<T>>
+}
+
+/** Parent expectations */
+export interface ExpectationsParent {
+  context: Expectations,
+  prop: string | number | symbol,
+}
+
+/** Basic definition of an {@link Expectation} as an object */
+export interface Expectation {
+  expect(context: Expectations, negative: boolean, ...args: any[]): void
+}
+
+/* ========================================================================== *
+ * EXPECTATIONS IMPLEMENTATION                                                *
+ * ========================================================================== */
+
+/** Empty interface: the `class` below won't complain about missing stuff */
+interface ExpectationsImpl<T = unknown> extends Expectations<T> {}
+
+/** Implementation of our {@link Expectations} interface */
+class ExpectationsImpl<T = unknown> implements Expectations<T> {
+  private readonly _positiveExpectations: ExpectationsImpl<T>
+  private readonly _negativeExpectations: ExpectationsImpl<T>
+  private readonly _negative: boolean
+
+  constructor(
+      public readonly value: T,
+      _positiveExpectations?: ExpectationsImpl<T>,
+  ) {
+    if (_positiveExpectations) {
+      this._negative = true
+      this._positiveExpectations = _positiveExpectations
+      this._negativeExpectations = this
+    } else {
+      this._negative = false
+      this._positiveExpectations = this
+      this._negativeExpectations = new ExpectationsImpl(value, this)
+    }
+  }
+
+  /* == NEW EXPECTATIONS ==================================================== */
+
+  forProperty(prop: string | number | symbol): ExpectationsImpl {
+    this.toBeDefined()
+
+    const child = new ExpectationsImpl((this.value as any)[prop])
+    child.parent = { context: this, prop }
+    return child
+  }
+
+  forValue<T = unknown>(value: T): ExpectationsImpl<T> {
+    return new ExpectationsImpl(value)
+  }
+
+  /* == NEGATION ============================================================ */
+
+  negated(negative: boolean): ExpectationsImpl<T> {
+    return negative ? this._negativeExpectations : this._positiveExpectations
+  }
+
+  get not(): ExpectationsImpl<T> {
+    return this._negative ? this._positiveExpectations : this._negativeExpectations
+  }
+
+  /* == ASYNCHRONOUS EXPECTATIONS =========================================== */
+
+  toBeResolved(assert?: (resultExpectations: Expectations) => void): Promise<ExpectationsImpl<T>> {
+    return Promise.resolve()
+        .then(() => {
+          this._positiveExpectations.toHaveProperty('then', (a) => a.toBeA('function'))
+          return Promise.allSettled([ Promise.resolve(this.value) ])
+        })
+        .then(([ settlement ]) => {
+          if (settlement.status === 'fulfilled') {
+            if (this._negative) throw new ExpectationError(this, true, 'to be resolved')
+            if (assert) assert(new ExpectationsImpl(settlement.value))
+          } else if (! this._negative) {
+            throw new ExpectationError(this, false, 'to be resolved')
+          }
+
+          return this._positiveExpectations
+        })
+  }
+
+  toBeRejected(assert?: (reasonExpectations: Expectations) => void): Promise<ExpectationsImpl<T>> {
+    return Promise.resolve()
+        .then(() => {
+          this._positiveExpectations.toHaveProperty('then', (a) => a.toBeA('function'))
+          return Promise.allSettled([ Promise.resolve(this.value) ])
+        })
+        .then(([ settlement ]) => {
+          if (settlement.status === 'rejected') {
+            if (this._negative) throw new ExpectationError(this, true, 'to be rejected')
+            if (assert) assert(new ExpectationsImpl(settlement.reason))
+          } else if (! this._negative) {
+            throw new ExpectationError(this, false, 'to be rejected')
+          }
+
+          return this._positiveExpectations
+        })
+  }
+
+  toBeRejectedWithError(
+      ...args:
+      | []
+      | [ message: StringMatcher ]
+      | [ constructor: Constructor<Error> ]
+      | [ constructor: Constructor<Error>, message: StringMatcher ]
+  ): Promise<ExpectationsImpl<T>> {
+    return this.toBeRejected((assert) => assert.toBeError(...args))
+  }
+
+  /* == STATIC INITALIZER =================================================== */
+
+  static {
+    for (const [ key, value ] of Object.entries(expectations)) {
+      const expectation = value as Expectation
+
+      const fn = function(this: ExpectationsImpl, ...args: any[]): any {
+        try {
+          expectation.expect(this._positiveExpectations, this._negative, ...args)
+          return this._positiveExpectations
+        } catch (error) {
+          if (error instanceof ExpectationError) Error.captureStackTrace(error, fn)
+          throw error
+        }
+      }
+
+      Object.defineProperty(fn, 'name', { value: key })
+      Object.defineProperty(this.prototype, key, { value: fn })
+    }
+  }
+}
+
+/* ========================================================================== *
+ * EXPECTATIONS MATCHERS                                                      *
+ * ========================================================================== */
+
+/** Infer return parameter from {@link Expectation} type */
+type MatcherReturn<E> = E extends Expectation ? ExpectationsMatcher : never
+
+/** Infer expectation functions from imported {@link Expectation} instances */
+type ImportedMatchers = {
+  [ k in keyof ExpectationsByName ]: (
+    ...args: ExpectationParameters<ExpectationsByName[k]>
+  ) => MatcherReturn<ExpectationsByName[k]>
+}
+
+/** An interface describing all expectations returned by `expect(...)` */
+export interface ExpectationsMatcher extends ImportedMatchers {
+  not: ExpectationsMatcher
+  expect(value: unknown): void
+}
+
+
+interface ExpectationsMatcherImpl extends ExpectationsMatcher {}
+
+class ExpectationsMatcherImpl {
+  private readonly _matchers: readonly [ string, boolean, any[] ][]
+  private readonly _positiveBuilder: ExpectationsMatcherImpl
+  private readonly _negativeBuilder: ExpectationsMatcherImpl
+  private readonly _negative: boolean
+
+  constructor(
+      _matchers: readonly [ string, boolean, any[] ][],
+      _positiveBuilder?: ExpectationsMatcherImpl,
+  ) {
+    this._matchers = _matchers
+    if (_positiveBuilder) {
+      this._negative = true
+      this._positiveBuilder = _positiveBuilder
+      this._negativeBuilder = this
+    } else {
+      this._negative = false
+      this._positiveBuilder = this
+      this._negativeBuilder = new ExpectationsMatcherImpl(this._matchers, this)
+    }
+  }
+
+  get not(): ExpectationsMatcherImpl {
+    return this._negative ? this._positiveBuilder : this._negativeBuilder
+  }
+
+  expect(value: unknown): void {
+    const expectations = new ExpectationsImpl(value)
+    for (const [ expectation, negative, args ] of this._matchers) {
+      (expectations.negated(negative) as any)[expectation](...args)
+    }
+  }
+
+  /* == STATIC INITALIZER =================================================== */
+
+  static {
+    // for "isMatcher(...)" used by "diff(...)"
+    Object.defineProperty(this.prototype, matcherMarker, { value: matcherMarker })
+
+    // all our matchers
+    for (const key in expectations) {
+      Object.defineProperty(this.prototype, key, {
+        value: function(this: ExpectationsMatcherImpl, ...args: any[]): any {
+          return new ExpectationsMatcherImpl([
+            ...this._matchers, [ key, this._negative, args ],
+          ])
+        },
+      })
+    }
+  }
+}
+
+/* ========================================================================== *
+ * EXPECT FUNCTION                                                            *
+ * ========================================================================== */
+
+/** The `expect` function exposing expectations and matchers */
+export const expect = (<T = unknown>(value: T): Expectations<T> => {
+  return new ExpectationsImpl(value)
+}) as ExpectationsMatcher & (<T = unknown>(value: T) => Expectations<T>)
+
+// Instrument a getter for negative matchers
+Object.defineProperty(expect, 'not', {
+  get: () => new ExpectationsMatcherImpl([]).not,
+})
+
+// Create a matcher for each expectation
+for (const name in expectations) {
+  Object.defineProperty(expect, name, {
+    value: function(...args: any[]): ExpectationsMatcher {
+      const builder = new ExpectationsMatcherImpl([])
+      return (builder as any)[name](...args)
+    },
+  })
+}

package/src/expectation/include.ts

@@ -0,0 +1,184 @@
+import { diff } from './diff'
+import { ExpectationError, stringifyObjectType, stringifyValue } from './types'
+
+import type { Diff } from './diff'
+import type { Expectation, Expectations } from './expect'
+
+export class ToInclude implements Expectation {
+  expect(
+      context: Expectations,
+      negative: boolean,
+      expected:
+      | Record<string, any>
+      | Map<any, any>
+      | Set<any>
+      | any [],
+  ): void {
+    // get diff depending on type of "expected"
+    if (expected instanceof Map) return includesMappings(context, negative, expected)
+    if (expected instanceof Set) return includesValues(context, negative, expected)
+    if (Array.isArray(expected)) return includesValues(context, negative, new Set(expected))
+    if (expected instanceof Object) return includesProps(context, negative, expected)
+    throw new TypeError(`Invalid type for "toInclude(...)": ${stringifyValue(expected)}`)
+  }
+}
+
+export class ToMatchContents implements Expectation {
+  expect(
+      context: Expectations,
+      negative: boolean,
+      contents: any[] | Set<any>,
+  ): void {
+    let actual: Set<any>
+    let expected: Set<any>
+    try {
+      actual = new Set(context.value as any)
+      expected = new Set(contents)
+    } catch (error) {
+      throw new ExpectationError(context, false, 'to be an iterable object')
+    }
+
+    const result = diff(actual, expected)
+    delete result.error // remove extra error message about size differences...
+    if (result.diff === negative) return
+    throw new ExpectationError(
+        context,
+        negative,
+        `to match contents of ${stringifyObjectType(contents)}`,
+        { ...result, value: context.value })
+  }
+}
+
+export function includesProps(context: Expectations, negative: boolean, expected: Record<string, any>): void {
+  // simple include for maps with objects...
+  if (context.value instanceof Map) {
+    return includesMappings(context, negative, new Map(Object.entries(expected)))
+  }
+
+  // we really need an object as actual
+  context.toBeInstanceOf(Object)
+  const actual: Record<string, any> = context.value as any
+
+  // get expected key set and process...
+  const keys = new Set(Object.keys(expected))
+  const props: Record<string, Diff> = {}
+
+  if (negative) {
+    // only consider keys... if they exist, fail!
+    for (const key of keys) {
+      if ((actual[key] !== undefined) || (key in actual)) {
+        props[key] = { diff: true, extra: actual[key] }
+      }
+    }
+  } else {
+    for (const key of keys) {
+      const act = actual[key]
+      const exp = expected[key]
+
+      const result = diff(act, exp)
+      if (! result.diff) continue
+
+      // if there is a difference, we _might_ have a missing/extra property
+      if ((act === undefined) && (! (key in actual))) {
+        props[key] = { diff: true, missing: exp }
+      } else {
+        props[key] = result
+      }
+    }
+  }
+
+  const count = Object.keys(props).length
+  if (count === 0) return // no props? no errors!
+
+  const type = count === 1 ? 'property' : 'properties'
+  throw new ExpectationError(context, negative, `to include ${count} ${type}`, {
+    diff: true,
+    value: actual,
+    props,
+  })
+}
+
+export function includesValues(context: Expectations, negative: boolean, expected: Set<any>): void {
+  // we really need an _iterable_ object as actual
+  context.toBeInstanceOf(Object)
+  if (typeof (context.value as any)[Symbol.iterator] !== 'function') {
+    throw new ExpectationError(context, false, 'to be an iterable object')
+  }
+  const actual = new Set(context.value as Iterable<any>)
+
+  // iterate through all the values and see what we can find
+  const values: Diff[] = []
+  if (negative) {
+    for (const exp of expected) {
+      for (const act of actual) {
+        const result = diff(act, exp)
+        if (result.diff) continue
+
+        values.push({ diff: true, extra: act })
+        break
+      }
+    }
+  } else {
+    for (const exp of expected) {
+      let found = false
+
+      for (const act of actual) {
+        const result = diff(act, exp)
+        if (result.diff) continue
+        found = true
+        break
+      }
+
+      if (! found) {
+        values.push({ diff: true, missing: exp })
+      }
+    }
+  }
+
+  const count = values.length
+  if (count === 0) return // no values? no errors!
+
+  const type = count === 1 ? 'value' : 'values'
+  throw new ExpectationError(context, negative, `to include ${count} ${type}`, {
+    diff: true,
+    value: context.value,
+    values,
+  })
+}
+
+export function includesMappings(context: Expectations, negative: boolean, expected: Map<any, any>): void {
+  context.toBeInstanceOf(Map)
+  const actual: Map<any, any> = context.value as any
+
+  // Get expected key set and process...
+  const keys = new Set(expected.keys())
+  const mappings: [ string, Diff ][] = []
+
+  if (negative) {
+    // only consider keys... if they exist, fail!
+    for (const key of keys) {
+      if (actual.has(key)) {
+        mappings.push([ key, { diff: true, extra: actual.get(key) } ])
+      }
+    }
+  } else {
+    for (const key of keys) {
+      if (! actual.has(key)) {
+        mappings.push([ key, { diff: true, missing: expected.get(key) } ])
+      } else {
+        const result = diff(actual.get(key), expected.get(key))
+        if (result.diff) mappings.push([ key, result ])
+      }
+    }
+  }
+
+  const count = mappings.length
+  if (count === 0) return // no mappings? no errors!
+
+  const type = count === 1 ? 'mapping' : 'mappings'
+  throw new ExpectationError(context, negative, `to include ${count} ${type}`, {
+    diff: true,
+    value: context.value,
+    mappings,
+  })
+}