Released version 3.4.0

README.md

@@ -1,9 +1,9 @@
 [![npm version](https://badge.fury.io/js/%40cowwoc%2Frequirements.svg)](https://badge.fury.io/js/%40cowwoc%2Frequirements)
 [![build-status](https://github.com/cowwoc/requirements.js/workflows/Build/badge.svg)](https://github.com/cowwoc/requirements.js/actions?query=workflow%3ABuild)
 
-# <img src="https://raw.githubusercontent.com/cowwoc/requirements.js/release-3.3.0/docs/checklist.svg?sanitize=true" width=64 height=64 alt="checklist"> Fluent API for Design Contracts
+# <img src="https://raw.githubusercontent.com/cowwoc/requirements.js/release-3.4.0/docs/checklist.svg?sanitize=true" width=64 height=64 alt="checklist"> Fluent API for Design Contracts
 
-[![API](https://img.shields.io/badge/api_docs-5B45D5.svg)](https://cowwoc.github.io/requirements.js/3.3.0/docs/api/)
+[![API](https://img.shields.io/badge/api_docs-5B45D5.svg)](https://cowwoc.github.io/requirements.js/3.4.0/docs/api/)
 [![Changelog](https://img.shields.io/badge/changelog-A345D5.svg)](wiki/Changelog.md)
 [![java](https://img.shields.io/badge/other%20languages-java-457FD5.svg)](../../../requirements.java)
 
@@ -17,13 +17,13 @@ A [fluent API](https://en.wikipedia.org/wiki/Fluent_interface) for enforcing
 To get started, add this dependency:
 
 ```shell
-npm install --save @cowwoc/requirements@3.3.3
+npm install --save @cowwoc/requirements@3.4.0
 ```
 
 or [pnpm](https://pnpm.io/):
 
 ```shell
-pnpm add @cowwoc/requirements@3.3.3
+pnpm add @cowwoc/requirements@3.4.0
 ```
 
 The contents of the API classes depend on which [modules](wiki/Supported_Libraries.md) are enabled.
@@ -90,13 +90,13 @@ Actual: 15
 The best way to learn about the API is using your IDE's auto-complete engine.
 There are six entry points you can navigate from:
 
-* [requireThat(value, name)](https://cowwoc.github.io/requirements.js/3.3.0/docs/api/module-DefaultRequirements.html#~requireThat)
-* [validateThat(value, name)](https://cowwoc.github.io/requirements.js/3.3.0/docs/api/module-DefaultRequirements.html#~validateThat)
-* [assertThat(Function)](https://cowwoc.github.io/requirements.js/3.3.0/docs/api/module-DefaultRequirements.html#~assertThat)
-* [assertThatAndReturn(Function)](https://cowwoc.github.io/requirements.js/3.3.0/docs/api/module-DefaultRequirements.html#~assertThatAndReturn)
+* [requireThat(value, name)](https://cowwoc.github.io/requirements.js/3.4.0/docs/api/module-DefaultRequirements.html#~requireThat)
+* [validateThat(value, name)](https://cowwoc.github.io/requirements.js/3.4.0/docs/api/module-DefaultRequirements.html#~validateThat)
+* [assertThat(Function)](https://cowwoc.github.io/requirements.js/3.4.0/docs/api/module-DefaultRequirements.html#~assertThat)
+* [assertThatAndReturn(Function)](https://cowwoc.github.io/requirements.js/3.4.0/docs/api/module-DefaultRequirements.html#~assertThatAndReturn)
 
-* [Requirements](https://cowwoc.github.io/requirements.js/3.3.0/docs/api/module-Requirements-Requirements.html)
-* [GlobalRequirements](https://cowwoc.github.io/requirements.js/3.3.0/docs/api/module-GlobalRequirements-GlobalRequirements.html)
+* [Requirements](https://cowwoc.github.io/requirements.js/3.4.0/docs/api/module-Requirements-Requirements.html)
+* [GlobalRequirements](https://cowwoc.github.io/requirements.js/3.4.0/docs/api/module-GlobalRequirements-GlobalRequirements.html)
 
 ## Best practices
 

docs/Changelog.md

@@ -1,9 +1,31 @@
 Minor updates involving cosmetic changes have been omitted from this list. See
 https://github.com/cowwoc/requirements.java/commits/master for a full list.
 
+## Version 3.4.0 - 2023/12/04
+
+* Breaking changes: The following `ObjectVerifier` methods now throw `TypeError` instead of `RangeError` if the actual
+  value does not have the desired type:
+  * `isNull()`
+  * `isNotNull()`
+  * `isDefined()`
+  * `isUndefined()`
+  * `isDefinedAndNotNull`
+  * `isUndefinedOrNull`
+  * `isBoolean()`
+  * `isNumber()`
+  * `isString()`
+  * `isInetAddress()`
+  * `isClass()`
+  * `isArray()`
+  * `isSet()`
+  * `isMap()`
+  * `isPrimitive()`
+  * `isTypeOf()`
+  * `isInstanceOf()`
+
 ## Version 3.3.3 - 2023/12/04
 
-* Bugfix: 3.3.2 release was missing browser files
+* Bugfix: 3.3.2 release was missing browser files.
 
 ## Version 3.3.2 - 2023/11/30
 

docs/Features.md

@@ -72,7 +72,7 @@ requireThat(nameToAge, "nameToAge").asMap().
 
 ## String diff
 
-When a [String comparison](https://cowwoc.github.io/requirements.js/3.3.0/docs/api/ObjectVerifier.html#isEqualTo)
+When a [String comparison](https://cowwoc.github.io/requirements.js/3.4.0/docs/api/ObjectVerifier.html#isEqualTo)
 fails, the library outputs a [diff](String_Diff.md) of the values being compared.
 
 ![colored-diff-example4.png](colored-diff-example4.png)

docs/String_Diff.md

@@ -1,4 +1,4 @@
-When a [String comparison](https://cowwoc.github.io/requirements.js/3.3.0/docs/api/ObjectVerifier.html#isEqualTo)
+When a [String comparison](https://cowwoc.github.io/requirements.js/3.4.0/docs/api/ObjectVerifier.html#isEqualTo)
 fails, the library outputs a [diff](https://en.wikipedia.org/wiki/Diff) of the values being compared.
 
 Depending on the terminal capability, you will see a [Textual](Textual_Diff.md) or [Colored](Colored_Diff.md) diff.

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cowwoc/requirements",
-	"version": "3.3.3",
+	"version": "3.4.0",
 	"keywords": [
 		"preconditions",
 		"postconditions",

src/extension/ExtensibleObjectValidator.mts

@@ -137,6 +137,16 @@ interface ExtensibleObjectValidator<S, T>
 	isPrimitive<T2 extends T = T & (string | number | bigint | boolean | null | undefined | symbol)>():
 		ObjectValidator<T2>;
 
+	/**
+	 * Ensures that <code>typeof(actual)</code> is equal to <code>type</code>.
+	 *
+	 * @param type - the expected
+	 * <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof">typeof</a>
+	 * of the actual value
+	 * @returns the updated validator
+	 */
+	isTypeOf(type: string): S;
+
 	/**
 	 * Ensures that the actual value is an instance of an array or class.
 	 *
@@ -169,16 +179,6 @@ interface ExtensibleObjectValidator<S, T>
 	 */
 	isNotEqualTo(value: T, name?: string): S;
 
-	/**
-	 * Ensures that <code>typeof(actual)</code> is equal to <code>type</code>.
-	 *
-	 * @param type - the expected
-	 * <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof">typeof</a>
-	 * of the actual value
-	 * @returns the updated validator
-	 */
-	isTypeOf(type: string): S;
-
 	/**
 	 * Returns the actual value.
 	 *

src/extension/ExtensibleObjectVerifier.mts

@@ -26,79 +26,79 @@ interface ExtensibleObjectVerifier<S, T>
 	 * Ensures that the actual value is null.
 	 *
 	 * @returns the updated verifier
-	 * @throws RangeError if the actual value is not null
+	 * @throws TypeError if the actual value is not null
 	 */
 	isNull(): ObjectVerifier<null>;
 
 	/**
 	 * Ensures that the actual value is not null.
 	 *
 	 * @returns the updated verifier
-	 * @throws RangeError if the actual value is null
+	 * @throws TypeError if the actual value is null
 	 */
 	isNotNull(): ObjectVerifier<Exclude<T, null>>;
 
 	/**
 	 * Ensures that the actual value is defined.
 	 *
 	 * @returns the updated verifier
-	 * @throws RangeError if the actual value is undefined
+	 * @throws TypeError if the actual value is undefined
 	 */
 	isDefined<T2 = Exclude<T, undefined>>(): ObjectVerifier<T2>;
 
 	/**
 	 * Ensures that the actual value is undefined.
 	 *
 	 * @returns the updated verifier
-	 * @throws RangeError if the actual value is not undefined
+	 * @throws TypeError if the actual value is not undefined
 	 */
 	isUndefined(): ObjectVerifier<undefined>;
 
 	/**
 	 * Ensures that the actual value is not undefined or null.
 	 *
 	 * @returns the updated verifier
-	 * @throws RangeError if the value is undefined or null
+	 * @throws TypeError if the value is undefined or null
 	 */
 	isDefinedAndNotNull<T2 = Exclude<T, undefined | null>>(): ObjectVerifier<T2>;
 
 	/**
 	 * Ensures that the actual value is not undefined or null.
 	 *
 	 * @returns the updated verifier
-	 * @throws RangeError if the value is not undefined or null
+	 * @throws TypeError if the value is not undefined or null
 	 */
 	isUndefinedOrNull<T2 extends T = T & (undefined | null)>(): ObjectVerifier<T2>;
 
 	/**
 	 * Ensures that the actual value is a boolean.
 	 *
 	 * @returns a verifier for the <code>boolean</code>
-	 * @throws RangeError if the actual value is not a <code>boolean</code>
+	 * @throws TypeError if the actual value is not a <code>boolean</code>
 	 */
 	isBoolean(): BooleanVerifier;
 
 	/**
 	 * Ensures that the actual value is a number.
 	 *
 	 * @returns a verifier for the <code>number</code>
-	 * @throws RangeError if the actual value is not a <code>number</code>
+	 * @throws TypeError if the actual value is not a <code>number</code>
 	 */
 	isNumber(): NumberVerifier;
 
 	/**
 	 * Ensures that the actual value is a string.
 	 *
 	 * @returns a verifier for the <code>string</code>
-	 * @throws RangeError if the actual value is not a <code>string</code>
+	 * @throws TypeError if the actual value is not a <code>string</code>
 	 */
 	isString(): StringVerifier;
 
 	/**
 	 * Ensures that the actual value is an internet address.
 	 *
 	 * @returns a verifier for the internet address
-	 * @throws RangeError if the actual value is not an internet address
+	 * @throws TypeError if the actual value is not an internet address
 	 */
 	isInetAddress(): InetAddressVerifier;
 
@@ -108,7 +108,7 @@ interface ExtensibleObjectVerifier<S, T>
 	 * @typeParam T2 - the type of the class
 	 * @param type - the type of class to check for
 	 * @returns a verifier for the object's class representation
-	 * @throws RangeError if the actual value is not a class constructor
+	 * @throws TypeError if the actual value is not a class constructor
 	 */
 	isClass<T2>(type: ClassConstructor<T2>): ClassVerifier<T2>;
 
@@ -117,7 +117,7 @@ interface ExtensibleObjectVerifier<S, T>
 	 *
 	 * @typeParam E - the type of elements in the array
 	 * @returns a verifier for the <code>Array</code>
-	 * @throws RangeError if the actual value is not an <code>Array</code>
+	 * @throws TypeError if the actual value is not an <code>Array</code>
 	 */
 	isArray<E = ElementOf<T>>(): ArrayVerifier<E>;
 
@@ -126,7 +126,7 @@ interface ExtensibleObjectVerifier<S, T>
 	 *
 	 * @typeParam E - the type of elements in the set
 	 * @returns a verifier for the <code>Set</code>
-	 * @throws RangeError if the actual value is not a <code>Set</code>
+	 * @throws TypeError if the actual value is not a <code>Set</code>
 	 */
 	isSet<E = ElementOf<T>>(): SetVerifier<E>;
 
@@ -136,7 +136,7 @@ interface ExtensibleObjectVerifier<S, T>
 	 * @typeParam K - the type of keys in the map
 	 * @typeParam K - the type of values in the map
 	 * @returns a verifier for the <code>Map</code>
-	 * @throws RangeError if the actual value is not a <code>Map</code>
+	 * @throws TypeError if the actual value is not a <code>Map</code>
 	 */
 	isMap<K = MapKey<T>, V = MapValue<T>>(): MapVerifier<K, V>;
 
@@ -147,18 +147,30 @@ interface ExtensibleObjectVerifier<S, T>
 	 * To check if the actual value is an object, use <code>isInstanceOf(Object)</code>.
 	 *
 	 * @returns the updated verifier
+	 * @throws TypeError if the actual value is not a primitive type
 	 */
 	isPrimitive<T2 extends T = T & (string | number | bigint | boolean | null | undefined | symbol)>():
 		ObjectVerifier<T2>;
 
+	/**
+	 * Ensures that <code>typeof(actual)</code> is equal to <code>type</code>.
+	 *
+	 * @param type - the expected
+	 * <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof">typeof</a>
+	 * of the actual value
+	 * @returns the updated verifier
+	 * @throws TypeError if <code>type</code> is not a string or if the actual value does not have the specified type
+	 */
+	isTypeOf(type: string): S;
+
 	/**
 	 * Ensures that the actual value is an instance of a class.
 	 *
 	 * @typeParam T2 - the type of the actual value
-	 * @param type - the class constructor
+	 * @param type - a class constructor
 	 * @returns the updated validator
-	 * @throws TypeError if <code>type</code> is not a class
-	 * @throws RangeError if the actual value is not an instance of the specified class
+	 * @throws TypeError if <code>type</code> is not a class, or if the actual value is not an instance of the specified
+	 * class.
 	 */
 	isInstanceOf<T2>(type: ClassConstructor<T2>): ObjectVerifier<T2>;
 
@@ -186,16 +198,6 @@ interface ExtensibleObjectVerifier<S, T>
 	 */
 	isNotEqualTo(value: T, name?: string): S;
 
-	/**
-	 * Ensures that <code>typeof(actual)</code> is equal to <code>type</code>.
-	 *
-	 * @param type - the expected
-	 * <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof">typeof</a>
-	 * of the actual value
-	 * @returns the updated verifier
-	 */
-	isTypeOf(type: string): S;
-
 	/**
 	 * Returns the actual value.
 	 *