@plugjs/expect5 0.4.1 → 0.4.3

package/src/expectation/basic.ts

@@ -1,209 +1,409 @@
 import { diff } from './diff'
-import { assertType, ExpectationError, isType, prefixType, stringifyConstructor, stringifyValue } from './types'
+import {
+  assertContextType,
+  ExpectationError,
+  prefixType,
+  stringifyConstructor,
+  stringifyValue,
+  typeOf,
+} from './types'
 
-import type { Constructor, TypeName, StringMatcher } from './types'
-import type { Expectation, Expectations } from './expect'
+import type { Expectations } from './expect'
+import type {
+  AssertedType,
+  AssertionFunction,
+  Constructor,
+  ExpectationsContext,
+  JoinExpectations,
+  TypeMappings,
+  TypeName,
+} from './types'
 
-export class ToBeA implements Expectation {
-  expect(context: Expectations, negative: boolean, type: TypeName): void {
-    const match = isType(context, type)
-    if (match !== negative) return
-    throw new ExpectationError(context, negative, `to be ${prefixType(type)}`)
+/* === TO BE A ============================================================== */
+
+/** Expects the value to be of the specified {@link TypeName type}. */
+function toBeA<T extends TypeName>(type: T): Expectations<TypeMappings[T]>
+
+/**
+ * Expects the value to be of the specified {@link TypeName type}, and further
+ * asserts it with the specified callback.
+ */
+function toBeA<T extends TypeName>(type: T, assert: (valueExpectations: Expectations) => void): Expectations<TypeMappings[T]>
+
+/* Overloaded function implementation */
+function toBeA<T extends TypeName>(
+    this: ExpectationsContext,
+    type: T,
+    assert?: (valueExpectations: Expectations) => void,
+): Expectations {
+  const match = typeOf(this.value) === type
+  if (match === this.negative) {
+    throw new ExpectationError(this, `to be ${prefixType(type)}`)
+  } else if (assert) {
+    assert(this.expects)
   }
+  return this.expects
 }
 
-export class ToBeCloseTo implements Expectation {
-  expect(
-      context: Expectations,
-      negative: boolean,
-      ...[ value, delta ]:
-      | [ value: number, delta: number ]
-      | [ value: bigint, delta: bigint ]
-  ): void {
-    const min = (value as number) - (delta as number)
-    const max = (value as number) + (delta as number)
-    context.negated(negative).toBeWithinRange(min, max)
-  }
+/* === TO BE CLOSE TO ======================================================= */
+
+/**
+ * Expects the value to be a `number` within a given +/- delta range of the
+ * specified `number`.
+ */
+function toBeCloseTo(value: number, delta: number): Expectations<number>
+
+/**
+ * Expects the value to be a a `bigint` within a given +/- delta range of the
+ * specified `bigint`.
+ */
+function toBeCloseTo(value: bigint, delta: bigint): Expectations<bigint>
+
+/* Overloaded function implementation */
+function toBeCloseTo(
+    this: ExpectationsContext,
+    value: number | bigint,
+    delta: number | bigint,
+): Expectations {
+  const min = (value as number) - (delta as number)
+  const max = (value as number) + (delta as number)
+  return this.negated.toBeWithinRange(min, max)
 }
 
-export class ToBeError implements Expectation {
-  expect(
-      context: Expectations,
-      negative: boolean,
-      ...args:
-      | []
-      | [ message: StringMatcher ]
-      | [ constructor: Constructor<Error> ]
-      | [ constructor: Constructor<Error>, message: StringMatcher ]
-  ): void {
-    const [ constructor, message ] =
+/* === TO BE ERROR ========================================================== */
+
+/** Expects the value to be an {@link Error}. */
+function toBeError(): Expectations<Error>
+
+/** Expects the value to be an {@link Error} with the specified message. */
+function toBeError(message: string): Expectations<Error>
+
+/**
+ * Expects the value to be an {@link Error} with its message matching the
+ * specified {@link RegExp}.
+ */
+function toBeError(matcher: RegExp): Expectations<Error>
+
+/** Expects the value to be an {@link Error} of the specified _type_. */
+function toBeError<C extends Constructor<Error>>(constructor: C): Expectations<InstanceType<C>>
+
+/**
+ * Expects the value to be an {@link Error} of the specified _type_  with the
+ * specified message
+ */
+function toBeError<C extends Constructor<Error>>(constructor: C, message: string): Expectations<InstanceType<C>>
+
+/**
+ * Expects the value to be an {@link Error} of the specified _type_  with the
+ * specified message
+ */
+function toBeError<C extends Constructor<Error>>(constructor: C, matcher: RegExp): Expectations<InstanceType<C>>
+
+/* Overloaded function implementation */
+function toBeError(
+    this: ExpectationsContext,
+    ...args:
+    | []
+    | [ message: string | RegExp ]
+    | [ constructor: Constructor<Error> ]
+    | [ constructor: Constructor<Error>, message: string | RegExp ]
+): Expectations {
+  const [ constructor, message ] =
     typeof args[0] === 'function' ?
       [ args[0], args[1] ] :
       [ Error, args[0] ]
 
-    context.negated(negative).toBeInstanceOf(constructor)
-    if (negative || (message === undefined)) return // if "not.toBeError" ignore the message
+  this.negated.toBeInstanceOf(constructor)
 
-    context.toHaveProperty('message', (assert) => {
-      assertType(assert, 'string')
-      if (typeof message === 'string') assert.toStrictlyEqual(message)
-      else assert.toMatch(message)
-    })
-  }
+  // if "not.toBeError" ignore the message
+  if (this.negative || (message === undefined)) return this.expects
+
+  return this.expects.toHaveProperty('message', (assert) => {
+    assert.toBeA('string')
+    return typeof message === 'string' ?
+        assert.toStrictlyEqual(message) :
+        assert.toMatch(message)
+  })
 }
 
-export class ToBeGreaterThan implements Expectation {
-  expect(context: Expectations, negative: boolean, value: number | bigint): void {
-    assertType(context, typeof value as 'number' | 'bigint')
-    if ((context.value > value) !== negative) return
-    throw new ExpectationError(context, negative, `to be greater than ${stringifyValue(value)}`)
-  }
+
+/* === TO BE GREATER THAN =================================================== */
+
+/** Expects the value to be a `number` greater than the specified `number`. */
+function toBeGreaterThan(value: number): Expectations<number>
+/** Expects the value to be a `bigint` greater than the specified `bigint`. */
+function toBeGreaterThan(value: bigint): Expectations<bigint>
+
+/* Overloaded function implementation */
+function toBeGreaterThan(
+    this: ExpectationsContext,
+    value: number | bigint,
+): Expectations {
+  assertContextType(this, typeof value as 'number' | 'bigint')
+  if ((this.value > value) !== this.negative) return this.expects
+  throw new ExpectationError(this, `to be greater than ${stringifyValue(value)}`)
 }
 
-export class ToBeGreaterThanOrEqual implements Expectation {
-  expect(context: Expectations, negative: boolean, value: number | bigint): void {
-    assertType(context, typeof value as 'number' | 'bigint')
-    if ((context.value >= value) !== negative) return
-    throw new ExpectationError(context, negative, `to be greater than or equal to ${stringifyValue(value)}`)
-  }
+/* === TO BE GREATER THAN OR EQUAL ========================================== */
+
+/** Expects the value to be a `number` greater than or equal to the specified `number`. */
+function toBeGreaterThanOrEqual(value: number): Expectations<number>
+/** Expects the value to be a `bigint` greater than or equal to the specified `bigint`. */
+function toBeGreaterThanOrEqual(value: bigint): Expectations<bigint>
+
+/* Overloaded function implementation */
+function toBeGreaterThanOrEqual(
+    this: ExpectationsContext,
+    value: number | bigint,
+): Expectations {
+  assertContextType(this, typeof value as 'number' | 'bigint')
+  if ((this.value >= value) !== this.negative) return this.expects
+  throw new ExpectationError(this, `to be greater than or equal to ${stringifyValue(value)}`)
 }
 
-export class ToBeInstanceOf implements Expectation {
-  expect(context: Expectations, negative: boolean, value: Constructor): void {
-    const match = context.value instanceof value
-    if (match !== negative) return
-    throw new ExpectationError(context, negative, `to be an instance of ${stringifyConstructor(value)}`)
-  }
+/* === TO BE INSTANCE OF ==================================================== */
+
+/** Expects the value to be an instance of the specified _type_. */
+function toBeInstanceOf<C extends Constructor>(value: C): Expectations<InstanceType<C>>
+
+/* Overloaded function implementation */
+function toBeInstanceOf(
+    this: ExpectationsContext,
+    value: Constructor,
+): Expectations {
+  const match = this.value instanceof value
+  if (match !== this.negative) return this.expects
+  throw new ExpectationError(this, `to be an instance of ${stringifyConstructor(value)}`)
 }
 
-export class ToBeLessThan implements Expectation {
-  expect(context: Expectations, negative: boolean, value: number | bigint): void {
-    assertType(context, typeof value as 'number' | 'bigint')
-    if ((context.value < value) !== negative) return
-    throw new ExpectationError(context, negative, `to be less than ${stringifyValue(value)}`)
-  }
+/* === TO BE LESS THAN ====================================================== */
+
+/** Expects the value to be a `number` less than the specified `number`. */
+function toBeLessThan(value: number): Expectations<number>
+/** Expects the value to be a `bigint` less than the specified `bigint`. */
+function toBeLessThan(value: bigint): Expectations<bigint>
+
+/* Overloaded function implementation */
+function toBeLessThan(
+    this: ExpectationsContext,
+    value: number | bigint,
+): Expectations {
+  assertContextType(this, typeof value as 'number' | 'bigint')
+  if ((this.value < value) !== this.negative) return this.expects
+  throw new ExpectationError(this, `to be less than ${stringifyValue(value)}`)
 }
 
-export class ToBeLessThanOrEqual implements Expectation {
-  expect(context: Expectations, negative: boolean, value: number | bigint): void {
-    assertType(context, typeof value as 'number' | 'bigint')
-    if ((context.value <= value) !== negative) return
-    throw new ExpectationError(context, negative, `to be less than or equal to ${stringifyValue(value)}`)
-  }
+/* === TO BE LESS THAN OR EQUAL ============================================= */
+
+/** Expects the value to be a `number` less than or equal to the specified `number`. */
+function toBeLessThanOrEqual(value: number): Expectations<number>
+/** Expects the value to be a `bigint` less than or equal to the specified `bigint`. */
+function toBeLessThanOrEqual(value: bigint): Expectations<bigint>
+
+/* Overloaded function implementation */
+function toBeLessThanOrEqual(
+    this: ExpectationsContext,
+    value: number | bigint,
+): Expectations {
+  assertContextType(this, typeof value as 'number' | 'bigint')
+  if ((this.value <= value) !== this.negative) return this.expects
+  throw new ExpectationError(this, `to be less than or equal to ${stringifyValue(value)}`)
 }
 
-export class ToBeWithinRange implements Expectation {
-  expect(
-      context: Expectations,
-      negative: boolean,
-      ...[ min, max ]:
-      | [ min: number, max: number ]
-      | [ min: bigint, max: bigint ]
-  ): void {
-    if (max < min) {
-      const num = max
-      max = min
-      min = num
-    }
+/* === TO WITHIN RANGE ====================================================== */
+
+/** Expects the value to be a `number` within the specified range (inclusive). */
+function toBeWithinRange(min: number, max: number): Expectations<number>
+/** Expects the value to be a `bigint` within the specified range (inclusive). */
+function toBeWithinRange(min: bigint, max: bigint): Expectations<bigint>
 
-    assertType(context, typeof min as 'number' | 'bigint')
-    if (((context.value >= min) && (context.value <= max)) !== negative) return
-    throw new ExpectationError(context, negative, `to be within ${stringifyValue(min)}...${stringifyValue(max)}`)
+/* Overloaded function implementation */
+function toBeWithinRange(
+    this: ExpectationsContext,
+    min: number | bigint,
+    max: number | bigint,
+): Expectations {
+  if (max < min) {
+    const num = max
+    max = min
+    min = num
   }
+
+  assertContextType(this, typeof min as 'number' | 'bigint')
+  if (((this.value >= min) && (this.value <= max)) !== this.negative) return this.expects
+  throw new ExpectationError(this, `to be within ${stringifyValue(min)}...${stringifyValue(max)}`)
 }
 
-export class ToEqual implements Expectation {
-  expect(context: Expectations, negative: boolean, expected: any): void {
-    const result = diff(context.value, expected)
-    if (result.diff === negative) return
-    throw new ExpectationError(context, negative, `to equal ${stringifyValue(expected)}`, result)
-  }
+/* === TO EQUAL ============================================================= */
+
+/** Expects the value to _deeply equal_ to the specified expected value. */
+function toEqual<T>(expected: T): Expectations<T>
+
+/* Overloaded function implementation */
+function toEqual(
+    this: ExpectationsContext,
+    expected: any,
+): Expectations {
+  const result = diff(this.value, expected)
+  if (result.diff === this.negative) return this.expects
+  throw new ExpectationError(this, `to equal ${stringifyValue(expected)}`, result)
 }
 
-export class ToHaveLength implements Expectation {
-  expect(context: Expectations, negative: boolean, length: number): void {
-    context.toBeDefined()
+/* === TO HAVE LENGTH ======================================================= */
 
-    const actualLength = (context.value as any).length
-    if (typeof actualLength !== 'number') {
-      throw new ExpectationError(context, false, 'to have a numeric "length" property')
-    }
+/** Expects the value to have a numerical `length` property with the specified value. */
+function toHaveLength<T, N extends number>(this: T, length: N): JoinExpectations<T, { length: N }>
 
-    if ((actualLength === length) === negative) {
-      throw new ExpectationError(context, negative, `to have length ${stringifyValue(length)}`)
-    }
+/* Overloaded function implementation */
+function toHaveLength(
+    this: ExpectationsContext,
+    length: number,
+): Expectations {
+  this.expects.toBeDefined()
+
+  const actualLength = (this.value as any).length
+  if (typeof actualLength !== 'number') {
+    throw new ExpectationError(this, 'to have a numeric "length" property', false)
+  }
+
+  if ((actualLength === length) === this.negative) {
+    throw new ExpectationError(this, `to have length ${stringifyValue(length)}`)
   }
+
+  return this.expects
 }
 
-export class ToHaveProperty implements Expectation {
-  expect(
-      context: Expectations,
-      negative: boolean,
-      prop: string | number | symbol,
-      assert?: (propertyExpectations: Expectations) => void,
-  ): void {
-    context.toBeDefined()
-
-    const match = (context.value as any)[prop] !== undefined
-    if (match === negative) {
-      throw new ExpectationError(context, negative, `to have property "${String(prop)}"`)
-    } else if (match && assert) {
-      try {
-        assert(context.forProperty(prop))
-      } catch (error) {
-        // any caught error difference gets remapped as a property diff
-        if ((error instanceof ExpectationError) && (error.diff)) {
-          error.diff = {
-            diff: true,
-            value: context.value,
-            props: { [prop]: error.diff },
-          }
-        }
+/* === TO HAVE PROPERTY ===================================================== */
+
+/** Expects the value to have a property. */
+function toHaveProperty<T, P extends string | number | symbol, A extends AssertionFunction>(
+  this: T,
+  prop: P,
+): JoinExpectations<T, { [key in P]: AssertedType<A> }>
+
+/**
+ * Expects the value to have a property, and further asserts the property
+ * value with the specified callback.
+ */
+function toHaveProperty<T, P extends string | number | symbol, A extends AssertionFunction>(
+  this: T,
+  prop: P,
+  assert: A,
+): JoinExpectations<T, { [key in P]: AssertedType<A> }>
 
-        // re-throw
-        throw error
+/* Overloaded function implementation */
+function toHaveProperty(
+    this: ExpectationsContext,
+    prop: string | symbol | number,
+    assert?: AssertionFunction,
+): Expectations {
+  this.expects.toBeDefined()
+
+  const match = (this.value as any)[prop] !== undefined
+  if (match === this.negative) {
+    throw new ExpectationError(this, `to have property "${String(prop)}"`)
+  } else if (match && assert) {
+    try {
+      assert(this.forProperty(prop))
+    } catch (error) {
+      // any caught error difference gets remapped as a property diff
+      if ((error instanceof ExpectationError) && (error.diff)) {
+        error.diff = {
+          diff: true,
+          value: this.value,
+          props: { [prop]: error.diff },
+        }
       }
+
+      // re-throw
+      throw error
     }
   }
+
+  return this.expects
 }
 
-export class ToHaveSize implements Expectation {
-  expect(context: Expectations, negative: boolean, size: number): void {
-    context.toBeDefined()
 
-    const actualSize = (context.value as any).size
-    if (typeof actualSize !== 'number') {
-      throw new ExpectationError(context, false, 'to have a numeric "size" property')
-    }
+/* === TO HAVE SIZE ========================================================= */
 
-    if ((actualSize === size) === negative) {
-      throw new ExpectationError(context, negative, `to have size ${stringifyValue(size)}`)
-    }
+/** Expects the value to have a numerical `size` property with the specified value. */
+function toHaveSize<T, N extends number>(this: T, size: N): JoinExpectations<T, { size: N }>
+
+/* Overloaded function implementation */
+function toHaveSize(
+    this: ExpectationsContext,
+    size: number,
+): Expectations {
+  this.expects.toBeDefined()
+
+  const actualSize = (this.value as any).size
+  if (typeof actualSize !== 'number') {
+    throw new ExpectationError(this, 'to have a numeric "size" property', false)
   }
+
+  if ((actualSize === size) === this.negative) {
+    throw new ExpectationError(this, `to have size ${stringifyValue(size)}`)
+  }
+
+  return this.expects
 }
 
-export class ToMatch implements Expectation {
-  expect(
-      context: Expectations,
-      negative: boolean,
-      expr: StringMatcher,
-  ): void {
-    assertType(context, 'string')
+/* === TO MATCH ============================================================= */
 
-    const match = !! context.value.match(expr as string | RegExp) // meh, overloads
-    if (match !== negative) return
+/** Expects the value to be a `string` _matching_ the specified substring. */
+function toMatch(substring: string): Expectations<string>
+/** Expects the value to be a `string` _matching_ the specified {@link RegExp}. */
+function toMatch(expression: RegExp): Expectations<string>
 
-    throw new ExpectationError(context, negative, `to match ${stringifyValue(expr)}`)
-  }
+/* Overloaded function implementation */
+function toMatch(
+    this: ExpectationsContext,
+    expr: string | RegExp,
+): Expectations {
+  assertContextType(this, 'string')
+
+  const match = !! this.value.match(expr)
+  if (match !== this.negative) return this.expects
+
+  throw new ExpectationError(this, `to match ${stringifyValue(expr)}`)
 }
 
-export class ToStrictlyEqual implements Expectation {
-  expect(context: Expectations, negative: boolean, expected: any): void {
-    const value = context.value
-    const match = value === expected
-    if (match !== negative) return
 
-    const diff = negative ? undefined : { diff: true, value, expected }
-    throw new ExpectationError(context, negative, `to strictly equal ${stringifyValue(expected)}`, diff)
-  }
+/* === TO STRICTLY EQUAL ==================================================== */
+
+/** Expects the value to _strictly equal_ to the specified expected value. */
+function toStrictlyEqual<T>(expected: T): Expectations<T>
+
+/* Overloaded function implementation */
+function toStrictlyEqual(
+    this: ExpectationsContext,
+    expected: any,
+): Expectations {
+  // const value = context.value
+  const match = this.value === expected
+  if (match !== this.negative) return this.expects
+
+  const diff = this.negative ? undefined : { diff: true, value: this.value, expected }
+  throw new ExpectationError(this, `to strictly equal ${stringifyValue(expected)}`, diff)
+}
+
+/* === EXPORTS ============================================================== */
+
+/* coverage ignore next */
+export {
+  toBeA,
+  toBeCloseTo,
+  toBeError,
+  toBeGreaterThan,
+  toBeGreaterThanOrEqual,
+  toBeInstanceOf,
+  toBeLessThan,
+  toBeLessThanOrEqual,
+  toBeWithinRange,
+  toEqual,
+  toHaveLength,
+  toHaveProperty,
+  toHaveSize,
+  toMatch,
+  toStrictlyEqual,
 }

package/src/expectation/diff.ts

@@ -77,15 +77,14 @@ function objectDiff<T extends Record<string, any>>(
     const act = actual[key]
     const exp = expected[key]
 
-    let result = diffValues(act, exp, remarks)
-
-    // if there is a difference, we _might_ have a missing/extra property
-    if (result.diff) {
-      if ((act === undefined) && (key in expected)) {
-        result = { diff: true, missing: exp }
-      } else if ((exp === undefined) && (key in actual)) {
-        result = { diff: true, extra: act }
-      }
+    // check for missing/extra property or differences
+    let result: Diff
+    if ((key in expected) && (!(key in actual))) {
+      result = { diff: true, missing: exp }
+    } else if ((key in actual) && (!(key in expected))) {
+      result = { diff: true, extra: act }
+    } else {
+      result = diffValues(act, exp, remarks)
     }
 
     props[key] = result