* Removed methods that transform the actual value, such as asString()…

… or trim(). Users are expected to handle this outside the library.

* Removed consumer methods not used to validate class properties (e.g., asStringConsumer()).
* Renamed isNotDefined() to isUndefined().
* Renamed isNotFinite() to isInfinite().
* Removed all deprecated method declarations.

.mocharc.cjs

@@ -14,5 +14,4 @@ module.exports = {
 	exclude: [
 		"**/*.d.mts"
 	]
-	// slow: 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.2.3/wiki/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.3.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.2.3/docs/api/)
+[![API](https://img.shields.io/badge/api_docs-5B45D5.svg)](https://cowwoc.github.io/requirements.js/3.3.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.2.3
+npm install --save @cowwoc/requirements@3.3.0
 ```
 
 or [pnpm](https://pnpm.io/):
 
 ```shell
-pnpm add @cowwoc/requirements@3.2.3
+pnpm add @cowwoc/requirements@3.3.0
 ```
 
 The contents of the API classes depend on which [modules](wiki/Supported_Libraries.md) are enabled.
@@ -33,17 +33,40 @@ The contents of the API classes depend on which [modules](wiki/Supported_Librari
 ```typescript
 import {requireThat} from "@cowwoc/requirements";
 
-class Player
+
+class Address
+{
+}
+
+class PublicAPI
+{
+	constructor(name: string | null, age: number, address: Address | undefined)
+	{
+		// To validate user input, cast them to "unknown" prior to type-checks.
+		requireThat(name as unknown, "name").isString().length().isBetween(1, 30);
+		requireThat(age as unknown, "age").isNumber().isBetween(18, 30);
+
+		// Methods that conduct runtime type-checks, such as isString() or isNotNull(), update the
+		// compile-time type returned by getActual().
+		const nameIsString: string = requireThat(name as unknown, "name").isString().getActual();
+		const address: Address = requireThat(address as unknown, "address").isInstance(Address).getActual();
+	}
+}
+
+class PrivateAPI
 {
-	constructor(name, age)
+	public static toCamelCase(text): string
 	{
-		requireThat(name, "name").isNotNull().isInstanceOf(String).length().isBetween(1, 30);
-		requireThat(age, "age").isInstanceOf(Number).isBetween(18, 30);
+		// Trusted input does not need to be casted to "unknown". The input type will be inferred
+		// and runtime checks will be skipped. Notice the lack of isString() or isNumber() invocations
+		// in the following code.
+		assertThat(r => r.requireThat(name, "name").length().isBetween(1, 30));
+		assertThat(r => r.requireThat(age, "age").isBetween(18, 30));
 	}
 }
 ```
 
-Failure messages look like this:
+Failure messages will look like this:
 
 ```text
 TypeError: name may not be null
@@ -67,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.2.3/docs/api/module-DefaultRequirements.html#~requireThat)
-* [validateThat(value, name)](https://cowwoc.github.io/requirements.js/3.2.3/docs/api/module-DefaultRequirements.html#~validateThat)
-* [assertThat(Function)](https://cowwoc.github.io/requirements.js/3.2.3/docs/api/module-DefaultRequirements.html#~assertThat)
-* [assertThatAndReturn(Function)](https://cowwoc.github.io/requirements.js/3.2.3/docs/api/module-DefaultRequirements.html#~assertThatAndReturn)
+* [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)
 
-* [Requirements](https://cowwoc.github.io/requirements.js/3.2.3/docs/api/module-Requirements-Requirements.html)
-* [GlobalRequirements](https://cowwoc.github.io/requirements.js/3.2.3/docs/api/module-GlobalRequirements-GlobalRequirements.html)
+* [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)
 
 ## Best practices
 

build.mts

@@ -225,7 +225,9 @@ class Build
 		log.info("generateDocumentation()");
 		const targetDirectory = "target/apidocs/";
 
-		const app = await TypeDoc.Application.bootstrapWithPlugins({}, [
+		const app = await TypeDoc.Application.bootstrapWithPlugins({
+			excludeExternals: true
+		}, [
 			new TypeDoc.TypeDocReader(),
 			new TypeDoc.TSConfigReader()
 		]);

wiki/Changelog.md → docs/Changelog.md

@@ -1,6 +1,16 @@
 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.3.0 - 2023/11/29
+
+* Breaking changes
+  * Removed methods that transform the actual value, such as asString() or trim().
+    Users are expected to handle this outside the library.
+  * Removed consumer methods not used to validate class properties (e.g., asStringConsumer()).
+  * Renamed isNotDefined() to isUndefined().
+  * Renamed isNotFinite() to isInfinite().
+  * Removed all deprecated method declarations.
+
 ## Version 3.2.3 - 2023/11/23
 
 * Improvements

wiki/Features.md → docs/Features.md

@@ -3,7 +3,7 @@
 ```typescript
 const number = "1234567";
 
-requireThat(number, "number").asString().length().isLessThanOrEqualTo(5);
+requireThat(number as unknown, "number").isString().length().isLessThanOrEqualTo(5);
 ```
 
 ```text
@@ -72,7 +72,7 @@ requireThat(nameToAge, "nameToAge").asMap().
 
 ## String diff
 
-When a [String comparison](https://cowwoc.github.io/requirements.js/3.2.3/docs/api/ObjectVerifier.html#isEqualTo)
+When a [String comparison](https://cowwoc.github.io/requirements.js/3.3.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)

wiki/String_Diff.md → docs/String_Diff.md

@@ -1,4 +1,4 @@
-When a [String comparison](https://cowwoc.github.io/requirements.js/3.2.3/docs/api/ObjectVerifier.html#isEqualTo)
+When a [String comparison](https://cowwoc.github.io/requirements.js/3.3.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.2.3",
+	"version": "3.3.0",
 	"keywords": [
 		"preconditions",
 		"postconditions",
@@ -74,7 +74,7 @@
 		"ts-node": "^10.9.1",
 		"tslib": "^2.6.2",
 		"tsx": "^4.4.0",
-		"typedoc": "^0.25.3",
+		"typedoc": "^0.25.4",
 		"typedoc-plugin-missing-exports": "^2.1.0",
 		"typescript": "^5.3.2",
 		"typescript-eslint": "0.0.1-alpha.0",

src/ArrayValidator.mts

@@ -1,7 +1,6 @@
 import type {
 	ExtensibleObjectValidator,
 	NumberValidator,
-	SetValidator,
 	ObjectValidator
 } from "./internal/internal.mjs";
 
@@ -18,7 +17,7 @@ if (typedocWorkaround !== null)
  * {@link ExtensibleObjectValidator.getFailures | getFailures()} method, while Verifiers throw them as
  * exceptions.
  *
- * All methods (except those found in {@link ObjectValidator}) imply {@link isNotNull}.
+ * All methods (except those found in {@link ObjectValidator}) assume that the actual value is not null.
  *
  * @typeParam E - the type the array elements
  */
@@ -134,41 +133,6 @@ interface ArrayValidator<E> extends ExtensibleObjectValidator<ArrayValidator<E>,
 	 */
 	lengthConsumer(consumer: (length: NumberValidator) => void): ArrayValidator<E>;
 
-	/**
-	 * @returns a validator for the <code>Array</code>
-	 * @deprecated returns this
-	 */
-	asArray(): ArrayValidator<E>;
-
-	asArray<E>(): ArrayValidator<E>;
-
-	/**
-	 * @param consumer - a function that accepts a {@link ArrayValidator} for the actual value
-	 * @returns the updated validator
-	 * @throws TypeError if <code>consumer</code> is not set
-	 */
-	asArrayConsumer(consumer: (input: ArrayValidator<E>) => void): ArrayValidator<E>;
-
-	asArrayConsumer<E>(consumer: (input: ArrayValidator<E>) => void): ArrayValidator<E>;
-
-	/**
-	 * Verifies the Set representation of the array.
-	 *
-	 * @returns a <code>Set</code> validator
-	 */
-	asSet(): SetValidator<E>;
-
-	asSet<E>(): SetValidator<E>;
-
-	/**
-	 * @param consumer - a function that accepts a {@link SetValidator} for the Set representation of the array
-	 * @returns the updated validator
-	 * @throws TypeError if <code>consumer</code> is not set
-	 */
-	asSetConsumer(consumer: (actual: SetValidator<E>) => void): ArrayValidator<E>;
-
-	asSetConsumer<E>(consumer: (actual: SetValidator<E>) => void): ArrayValidator<E>;
-
 	/**
 	 * {@inheritDoc}
 	 */

src/ArrayVerifier.mts

@@ -1,7 +1,6 @@
 import type {
 	ExtensibleObjectVerifier,
 	NumberVerifier,
-	SetVerifier,
 	ObjectVerifier
 } from "./internal/internal.mjs";
 
@@ -13,7 +12,7 @@ if (typedocWorkaround !== null)
 /**
  * Verifies the requirements of an array.
  *
- * All methods (except those found in {@link ObjectVerifier}) imply {@link isNotNull}.
+ * All methods (except those found in {@link ObjectVerifier}) assume that the actual value is not null.
  *
  * @typeParam E - the type the array elements
  */
@@ -146,43 +145,6 @@ interface ArrayVerifier<E> extends ExtensibleObjectVerifier<ArrayVerifier<E>, E[
 	 */
 	lengthConsumer(consumer: (actual: NumberVerifier) => void): ArrayVerifier<E>;
 
-	/**
-	 * @returns a verifier for the <code>Array</code>
-	 * @throws TypeError if the actual value is not an <code>Array</code>
-	 * @deprecated returns this
-	 */
-	asArray(): ArrayVerifier<E>;
-
-	asArray<E>(): ArrayVerifier<E>;
-
-	/**
-	 * @param consumer - a function that accepts a {@link ArrayVerifier} for the actual value
-	 * @returns the updated verifier
-	 * @throws TypeError if <code>consumer</code> is not set.
-	 * If the actual value is not an <code>Array</code>.
-	 */
-	asArrayConsumer(consumer: (actual: ArrayVerifier<E>) => void): ArrayVerifier<E>;
-
-	asArrayConsumer<E>(consumer: (actual: ArrayVerifier<E>) => void): ArrayVerifier<E>;
-
-	/**
-	 * Verifies the Set representation of the array.
-	 *
-	 * @returns a <code>Set</code> verifier
-	 */
-	asSet(): SetVerifier<E>;
-
-	asSet<E>(): SetVerifier<E>;
-
-	/**
-	 * @param consumer - a function that accepts a {@link SetVerifier} for the Set representation of the array
-	 * @returns the updated verifier
-	 * @throws TypeError if <code>consumer</code> is not set
-	 */
-	asSetConsumer(consumer: (actual: SetVerifier<E>) => void): ArrayVerifier<E>;
-
-	asSetConsumer<E>(consumer: (actual: SetVerifier<E>) => void): ArrayVerifier<E>;
-
 	/**
 	 * {@inheritDoc}
 	 */

src/BooleanValidator.mts

@@ -8,7 +8,7 @@ import type {ExtensibleObjectValidator} from "./internal/internal.mjs";
  * {@link ExtensibleObjectValidator.getFailures | getFailures()} method, while Verifiers throw them as
  * exceptions.
  *
- * All methods (except those found in {@link ObjectValidator}) imply {@link isNotNull}.
+ * All methods (except those found in {@link ObjectValidator}) assume that the actual value is not null.
  */
 interface BooleanValidator extends ExtensibleObjectValidator<BooleanValidator, boolean>
 {

src/BooleanVerifier.mts

@@ -3,7 +3,7 @@ import type {ExtensibleObjectVerifier} from "./internal/internal.mjs";
 /**
  * Verifies the requirements of a <code>boolean</code>.
  * <p>
- * All methods (except those found in {@link ObjectVerifier}) imply {@link isNotNull}.
+ * All methods (except those found in {@link ObjectVerifier}) assume that the actual value is not null.
  */
 interface BooleanVerifier extends ExtensibleObjectVerifier<BooleanVerifier, boolean>
 {