@plugjs/expect5 0.4.1 → 0.4.3

package/src/expectation/include.ts

@@ -1,69 +1,103 @@
 import { diff } from './diff'
-import { ExpectationError, stringifyObjectType, stringifyValue } from './types'
+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)}`)
+import type { Expectations } from './expect'
+import type { ExpectationsContext } from './types'
+
+/* === TO INCLUDE =========================================================== */
+
+/** Expect the value to include _all_ properties from the specified _object_. */
+function toInclude<T, P extends Record<string, any>>(this: T, properties: P): T
+/** Expect the value to include _all_ mappings from the specified {@link Map}. */
+function toInclude<T>(this: T, mappings: Map<any, any>): T
+/** Expect the value to include _all_ values from the specified {@link Set}. */
+function toInclude<T>(this: T, entries: Set<any>): T
+/** Expect the value to include _all_ values in any order from the specified _array_. */
+function toInclude<T>(this: T, values: any[]): T
+
+/* Overloaded function implementation */
+function toInclude(
+    this: ExpectationsContext,
+    expected:
+    | Record<string, any>
+    | Map<any, any>
+    | Set<any>
+    | any [],
+): Expectations {
+  // get diff depending on type of "expected"
+  if (expected instanceof Map) return includesMappings(this, expected)
+  if (expected instanceof Set) return includesValues(this, expected)
+  if (Array.isArray(expected)) return includesValues(this, new Set(expected))
+  if (expected instanceof Object) return includesProps(this, expected)
+  throw new TypeError(`Invalid type for "toInclude(...)": ${stringifyValue(expected)}`)
+}
+
+/* === TO MATCH CONTENTS ==================================================== */
+
+/**
+ * Expect the value to include _all_ values (and only those values, in any
+ * order) from the specified _array_.
+ */
+function toMatchContents<T>(this: T, contents: any[]): T
+/**
+ * Expect the value to include _all_ values (and only those values, in any
+ * order) from the specified {@link Set}.
+ */
+function toMatchContents<T>(this: T, contents: Set<any>): T
+
+/* Overloaded function implementation */
+function toMatchContents(
+    this: ExpectationsContext,
+    contents: any[] | Set<any>,
+): Expectations {
+  let actual: Set<any>
+  let expected: Set<any>
+  try {
+    actual = new Set(this.value as any)
+    expected = new Set(contents)
+  } catch (error) {
+    throw new ExpectationError(this, 'to be an iterable object', false)
   }
+
+  const result = diff(actual, expected)
+  delete result.error // remove extra error message about size differences...
+  if (result.diff === this.negative) return this.expects
+  throw new ExpectationError(this,
+      `to match contents of ${stringifyObjectType(contents)}`,
+      { ...result, value: this.value })
 }
 
-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')
-    }
+/* === EXPORTS ============================================================== */
 
-    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 {
+  toInclude,
+  toMatchContents,
 }
 
-export function includesProps(context: Expectations, negative: boolean, expected: Record<string, any>): void {
+/* ========================================================================== *
+ * INTERNALS                                                                  *
+ * ========================================================================== */
+
+function includesProps(context: ExpectationsContext, expected: Record<string, any>): Expectations {
   // simple include for maps with objects...
   if (context.value instanceof Map) {
-    return includesMappings(context, negative, new Map(Object.entries(expected)))
+    return includesMappings(context, new Map(Object.entries(expected)))
   }
 
   // we really need an object as actual
-  context.toBeInstanceOf(Object)
+  context.expects.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) {
+  if (context.negative) {
     // only consider keys... if they exist, fail!
     for (const key of keys) {
       if ((actual[key] !== undefined) || (key in actual)) {
@@ -88,27 +122,27 @@ export function includesProps(context: Expectations, negative: boolean, expected
   }
 
   const count = Object.keys(props).length
-  if (count === 0) return // no props? no errors!
+  if (count === 0) return context.expects // no props? no errors!
 
   const type = count === 1 ? 'property' : 'properties'
-  throw new ExpectationError(context, negative, `to include ${count} ${type}`, {
+  throw new ExpectationError(context, `to include ${count} ${type}`, {
     diff: true,
     value: actual,
     props,
   })
 }
 
-export function includesValues(context: Expectations, negative: boolean, expected: Set<any>): void {
+function includesValues(context: ExpectationsContext, expected: Set<any>): Expectations {
   // we really need an _iterable_ object as actual
-  context.toBeInstanceOf(Object)
+  context.expects.toBeInstanceOf(Object)
   if (typeof (context.value as any)[Symbol.iterator] !== 'function') {
-    throw new ExpectationError(context, false, 'to be an iterable object')
+    throw new ExpectationError(context, 'to be an iterable object', false)
   }
   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) {
+  if (context.negative) {
     for (const exp of expected) {
       for (const act of actual) {
         const result = diff(act, exp)
@@ -136,25 +170,25 @@ export function includesValues(context: Expectations, negative: boolean, expecte
   }
 
   const count = values.length
-  if (count === 0) return // no values? no errors!
+  if (count === 0) return context.expects // no values? no errors!
 
   const type = count === 1 ? 'value' : 'values'
-  throw new ExpectationError(context, negative, `to include ${count} ${type}`, {
+  throw new ExpectationError(context, `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)
+function includesMappings(context: ExpectationsContext, expected: Map<any, any>): Expectations {
+  context.expects.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) {
+  if (context.negative) {
     // only consider keys... if they exist, fail!
     for (const key of keys) {
       if (actual.has(key)) {
@@ -173,10 +207,10 @@ export function includesMappings(context: Expectations, negative: boolean, expec
   }
 
   const count = mappings.length
-  if (count === 0) return // no mappings? no errors!
+  if (count === 0) return context.expects // no mappings? no errors!
 
   const type = count === 1 ? 'mapping' : 'mappings'
-  throw new ExpectationError(context, negative, `to include ${count} ${type}`, {
+  throw new ExpectationError(context, `to include ${count} ${type}`, {
     diff: true,
     value: context.value,
     mappings,

package/src/expectation/throwing.ts

@@ -1,45 +1,106 @@
-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))
-    }
+import { ExpectationError, assertContextType } from './types'
+
+import type { Expectations } from './expect'
+import type {
+  AssertionFunction,
+  Constructor,
+  ExpectationsContext,
+  JoinExpectations,
+} from './types'
+
+/* === TO THROW ============================================================= */
+
+/** Expects the value to be a `function` throwing _anything_. */
+function toThrow<T>(this: T): JoinExpectations<T, Function>
+
+/**
+ * Expects the value to be a `function` throwing, and asserts the
+ * thrown value with the specified callback.
+ */
+function toThrow<T>(this: T, assert: AssertionFunction): JoinExpectations<T, Function>
+
+/* Overloaded function implementation */
+function toThrow(
+    this: ExpectationsContext,
+    assert?: AssertionFunction,
+): Expectations {
+  assertContextType(this, 'function')
+
+  let thrown: boolean
+  let error: unknown
+  try {
+    this.value()
+    thrown = false
+    error = undefined
+  } catch (caught) {
+    thrown = true
+    error = caught
   }
-}
 
-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))
+  if (thrown === this.negative) {
+    throw new ExpectationError(this, 'to throw')
+  } else if (thrown && assert) {
+    assert(this.forValue(error))
   }
+
+  return this.expects
+}
+
+/* === TO THROW ERROR ======================================================= */
+
+/** Expects the value to be a `function` throwing an {@link Error}. */
+function toThrowError<T>(this: T): JoinExpectations<T, Function>
+
+/**
+ * Expects the value to be a `function` throwing an {@link Error} with the
+ * specified _message_.
+ */
+function toThrowError<T>(this: T, message: string): JoinExpectations<T, Function>
+
+/**
+ * Expects the value to be a `function` throwing an {@link Error} with its
+ * _message_ matching the specified {@link RegExp}.
+ */
+function toThrowError<T>(this: T, expession: RegExp): JoinExpectations<T, Function>
+
+/**
+ * Expects the value to be a `function` throwing an {@link Error} of the
+ * specified _type_.
+ */
+function toThrowError<T>(this: T, constructor: Constructor<Error>): JoinExpectations<T, Function>
+
+/**
+ * Expects the value to be a `function` throwing an {@link Error} of the
+ * specified _type_ with the specified _message_.
+ */
+function toThrowError<T>(this: T, constructor: Constructor<Error>, message: string): JoinExpectations<T, Function>
+
+/**
+ * Expects the value to be a `function` throwing an {@link Error} of the
+ * specified _type_ with its _message_ matching the specified {@link RegExp}.
+ */
+function toThrowError<T>(this: T, constructor: Constructor<Error>, expression: RegExp): JoinExpectations<T, Function>
+
+/* Overloaded function implementation */
+function toThrowError(
+    this: ExpectationsContext,
+    ...args:
+    | []
+    | [ string ]
+    | [ RegExp ]
+    | [ Constructor<Error> ]
+    | [ Constructor<Error>, string ]
+    | [ Constructor<Error>, RegExp ]
+): Expectations {
+  return this.negated.toThrow((assert) =>
+    // @ts-ignore // can't reconcile the types with overloads...
+    assert.toBeError(...args))
+}
+
+/* === EXPORTS ============================================================== */
+
+/* coverage ignore next */
+export {
+  toThrow,
+  toThrowError,
 }

package/src/expectation/trivial.ts

@@ -0,0 +1,107 @@
+import { ExpectationError, stringifyValue } from './types'
+
+import type { Expectations } from './expect'
+import type { ExpectationsContext } from './types'
+
+/* Expects the value to be _defined_ (that is not `null` nor `undefined`). */
+function toBeDefined<T>(this: T): T
+function toBeDefined(this: ExpectationsContext): Expectations {
+  return check(this, 'to be defined', (value) => (value !== null) && (value !== undefined))
+}
+
+/* Expects the value strictly equal to `false`. */
+function toBeFalse(): Expectations<false>
+function toBeFalse(this: ExpectationsContext): Expectations {
+  return check(this, `to be ${stringifyValue(false)}`, (value) => value === false)
+}
+
+/* Expects the value to be _falsy_ (zero, empty string, `false`, ...). */
+function toBeFalsy<T>(this: T): T
+function toBeFalsy(this: ExpectationsContext): Expectations {
+  return check(this, 'to be falsy', (value) => ! value)
+}
+
+/* Expects the value to be `NaN`. */
+function toBeNaN(): Expectations<number>
+function toBeNaN(this: ExpectationsContext): Expectations {
+  return check(this, `to be ${stringifyValue(NaN)}`, (value) => (typeof value === 'number') && isNaN(value))
+}
+
+/* Expects the value to strictly equal to `-Infinity` (negative infinity). */
+function toBeNegativeInfinity(): Expectations<number>
+function toBeNegativeInfinity(this: ExpectationsContext): Expectations {
+  return check(this, `to equal ${stringifyValue(Number.NEGATIVE_INFINITY)}`, (value) => value === Number.NEGATIVE_INFINITY)
+}
+
+/* Expects the value to strictly equal to `null`. */
+function toBeNull(): Expectations<null>
+function toBeNull(this: ExpectationsContext): Expectations {
+  return check(this, `to be ${stringifyValue(null)}`, (value) => value === null)
+}
+
+/* Expects the value to strictly equal to `null` or `undefined`. */
+function toBeNullable(): Expectations<null | undefined>
+function toBeNullable(this: ExpectationsContext): Expectations {
+  return check(
+      this,
+      `to be ${stringifyValue(null)} or ${stringifyValue(undefined)}`,
+      (value) => ((value === null) || (value === undefined)))
+}
+
+/* Expects the value to strictly equal to `+Infinity` (positive infinity). */
+function toBePositiveInfinity(): Expectations<number>
+function toBePositiveInfinity(this: ExpectationsContext): Expectations {
+  return check(this, `to equal ${stringifyValue(Number.POSITIVE_INFINITY)}`, (value) => value === Number.POSITIVE_INFINITY)
+}
+
+/* Expects the value to strictly equal to `true`. */
+function toBeTrue(): Expectations<true>
+function toBeTrue(this: ExpectationsContext): Expectations {
+  return check(this, `to be ${stringifyValue(true)}`, (value) => value === true)
+}
+
+/* Expects the value to be _falsy_ (non-zero, non-empty string, `true`, ...). */
+function toBeTruthy<T>(this: T): T
+function toBeTruthy(this:ExpectationsContext): Expectations {
+  return check(this, 'to be truthy', (value) => !! value)
+}
+
+/* Expects the value to strictly equal to `undefined`. */
+function toBeUndefined(): Expectations<undefined>
+function toBeUndefined(this: ExpectationsContext): Expectations {
+  return check(this, `to be ${stringifyValue(undefined)}`, (value) => value === undefined)
+}
+
+/* === EXPORTS ============================================================== */
+
+/* coverage ignore next */
+export {
+  toBeDefined,
+  toBeFalse,
+  toBeFalsy,
+  toBeNaN,
+  toBeNegativeInfinity,
+  toBeNull,
+  toBeNullable,
+  toBePositiveInfinity,
+  toBeTrue,
+  toBeTruthy,
+  toBeUndefined,
+}
+
+/* ========================================================================== *
+ * INTERNALS                                                                  *
+ * ========================================================================== */
+
+function check(
+    context: ExpectationsContext,
+    details: string,
+    cb: (value: unknown) => boolean,
+): Expectations {
+  const match = cb(context.value)
+  if (match === context.negative) {
+    throw new ExpectationError(context, details)
+  } else {
+    return context.expects
+  }
+}

package/src/expectation/types.ts

@@ -1,5 +1,9 @@
 import type { Diff } from './diff'
-import type { Expectations, ExpectationsMatcher } from './expect'
+import type { Expectations, Matchers, ExpectationFunctions } from './expect'
+
+/* ========================================================================== *
+ * INTERNAL TYPES FOR EXPECTATIONS                                            *
+ * ========================================================================== */
 
 /** A type identifying any constructor */
 export type Constructor<T = any> = new (...args: any[]) => T
@@ -14,11 +18,6 @@ export type NonArrayObject<T = any> = {
   [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"
@@ -45,6 +44,45 @@ export type TypeMappings = {
 /** Values returned by our own _expanded_ `{@link typeOf}` */
 export type TypeName = keyof TypeMappings
 
+/** Join the asserted type of an {@link Expectations} with another type */
+export type JoinExpectations<E, T2> =
+  E extends Expectations<infer T1> ? Expectations<T1 & T2> : Expectations<T2>
+
+/** An assertion function, for sub-expectations and value introspection */
+export type AssertionFunction<T = unknown> = (assert: Expectations<T>) => void | Expectations
+
+/** Get the type asserted by an {@link AssertionFunction} */
+export type AssertedType<F extends AssertionFunction<any>, R = ReturnType<F>> =
+  R extends Expectations<infer T> ? T : unknown
+
+/** Internal context used by expectations functions to operate */
+export interface ExpectationsContext<T = unknown> {
+  /** The value being expected */
+  readonly value: T,
+  /** Whether this is a negative or positive expectation */
+  readonly negative: boolean,
+  /** The optional parent of this instance, when constructed for a property */
+  readonly parent?: ExpectationsParent
+  /** The current _positive_ {@link Expectations} for the value */
+  readonly expects: Expectations<T>
+  /**
+   * If _negative_, the _negative_ {@link ExpectationFunctions} for the value,
+   * otherwise the _positive_ ones (basically, follow the `not` of `expect`).
+   */
+  readonly negated: ExpectationFunctions<T>
+
+  /** Create an {@link Expectation} instance for the specified value */
+  forValue<V>(value: V): Expectations<V>,
+  /** Create an {@link Expectation} instance for a property of this value */
+  forProperty(prop: string | number | symbol): Expectations
+}
+
+/** Parent expectations context (for properties) */
+export interface ExpectationsParent {
+  context: ExpectationsContext,
+  prop: string | number | symbol,
+}
+
 /* ========================================================================== *
  * TYPE INSPECTION, GUARD, AND ASSERTION                                      *
  * ========================================================================== */
@@ -81,24 +119,14 @@ export function typeOf(value: unknown): TypeName {
   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,
+export function assertContextType<T extends keyof TypeMappings>(
+    context: ExpectationsContext,
     type: T,
-): asserts context is Expectations<TypeMappings[T]> {
-  const { value } = context
-
-  if (typeOf(value) === type) return
+): asserts context is ExpectationsContext<TypeMappings[T]> {
+  if (typeOf(context.value) === type) return
 
-  throw new ExpectationError(context, false, `to be ${prefixType(type)}`)
+  throw new ExpectationError(context, `to be ${prefixType(type)}`, false)
 }
 
 /* ========================================================================== *
@@ -215,7 +243,7 @@ export function prefixType(type: TypeName): string {
 
 export const matcherMarker = Symbol.for('plugjs:expect5:types:ExpectationsMatcher')
 
-export function isMatcher(what: any): what is ExpectationsMatcher {
+export function isMatcher(what: any): what is Matchers {
   return what && what[matcherMarker] === matcherMarker
 }
 
@@ -226,12 +254,41 @@ export function isMatcher(what: any): what is ExpectationsMatcher {
 export class ExpectationError extends Error {
   diff?: Diff | undefined
 
+  /** Create an {@link ExpectationError} from a context and details message */
+  constructor(context: ExpectationsContext, details: string)
+
+  /**
+   * Create an {@link ExpectationError} from a context and details message,
+   * including an optional {@link Diff}
+   */
+  constructor(context: ExpectationsContext, details: string, diff?: Diff)
+
+  /**
+   * Create an {@link ExpectationError} from a context and details message,
+   * optionally forcing _negation_ to be as specified.
+   */
+  constructor(context: ExpectationsContext, details: string, forcedNegative?: boolean)
+
+  /**
+   * Create an {@link ExpectationError} from a context and details message,
+   * including an optional {@link Diff} and forcing _negation_ to be as
+   * specified.
+   */
+  constructor(context: ExpectationsContext, details: string, diff?: Diff, forcedNegative?: boolean)
+
+  /* Overloaded constructor implementation */
   constructor(
-      context: Expectations,
-      negative: boolean,
+      context: ExpectationsContext,
       details: string,
-      diff?: Diff,
+      diffOrForcedNegative?: Diff | boolean,
+      maybeForcedNegative?: boolean,
   ) {
+    const diff = typeof diffOrForcedNegative === 'object' ? diffOrForcedNegative : null
+    const negative =
+      typeof diffOrForcedNegative === 'boolean' ? diffOrForcedNegative :
+      typeof maybeForcedNegative === 'boolean' ? maybeForcedNegative :
+      context.negative
+
     const { value } = context
     const not = negative ? ' not' : ''
 

package/src/index.ts

@@ -16,6 +16,8 @@ export {
 export { skip } from './execution/executable'
 export { expect } from './expectation/expect'
 
+export type { Expectations } from './expectation/expect'
+
 /* ========================================================================== *
  * EXPORTED OPTIONS TYPE AND PLUG DEFINITION                                  *
  * ========================================================================== */