Fluent API for Design Contracts
+# 
Requirements API
-[](https://cowwoc.github.io/requirements.js/3.4.0/docs/api/)
-[](wiki/Changelog.md)
+[](https://cowwoc.github.io/requirements.js/4.0/docs/api/)
+[](docs/Changelog.md)
[](../../../requirements.java)
-A [fluent API](https://en.wikipedia.org/wiki/Fluent_interface) for enforcing
-[design contracts](https://en.wikipedia.org/wiki/Design_by_contract) with [automatic message generation](#usage).
+A [fluent API](https://en.m.wikipedia.org/docs/Fluent_interface) for enforcing
+[design contracts](https://en.wikipedia.org/docs/Design_by_contract) with
+[automatic message generation](docs/Features.md#automatic-message-generation):
✔️ Easy to use
✔️ Fast
@@ -17,93 +18,149 @@ 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.4.0
+npm install --save @cowwoc/requirements@4.0
```
or [pnpm](https://pnpm.io/):
```shell
-pnpm add @cowwoc/requirements@3.4.0
+pnpm add @cowwoc/requirements@4.0
```
-The contents of the API classes depend on which [modules](wiki/Supported_Libraries.md) are enabled.
-
-## Sample Code
+## Usage Example
```typescript
-import {requireThat} from "@cowwoc/requirements";
-
+import {requireThatString} from "@cowwoc/requirements";
-class Address
+class Cake
{
+ private bitesTaken = 0;
+ private piecesLeft;
+
+ public constructor(piecesLeft: number)
+ {
+ requireThat(piecesLeft, "piecesLeft").isPositive();
+ this.piecesLeft = piecesLeft;
+ }
+
+ public eat(): number
+ {
+ ++bitesTaken;
+ assertThat(bitesTaken, "bitesTaken").isNotNegative().elseThrow();
+
+ piecesLeft -= ThreadLocalRandom.current().nextInt(5);
+
+ assertThat(piecesLeft, "piecesLeft").isNotNegative().elseThrow();
+ return piecesLeft;
+ }
+
+ public getFailures(): String[]
+ {
+ return checkIf(bitesTaken, "bitesTaken").isNotNegative().
+ and(checkIf(piecesLeft, "piecesLeft").isGreaterThan(3)).
+ elseGetMessages();
+ }
}
+```
-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();
- }
-}
+If you violate a **precondition**:
-class PrivateAPI
-{
- public static toCamelCase(text): string
- {
- // 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));
- }
-}
+```typescript
+const cake = new Cake(-1000);
```
-Failure messages will look like this:
+You'll get:
-```text
-TypeError: name may not be null
+```
+RangeError: "piecesLeft" must be positive.
+actual: -1000
+```
+
+If you violate a **class invariant**:
+
+```typescript
+const cake = new Cake(1_000_000);
+while (true)
+ cake.eat();
+```
-RangeError: name may not be empty
+You'll get:
-RangeError: age must be in range [18, 30).
-Actual: 15
+```
+lang.AssertionError: "bitesTaken" may not be negative.
+actual: -128
+```
+
+If you violate a **postcondition**:
+
+```typescript
+const cake = new Cake(100);
+while (true)
+ cake.eat();
+```
+
+You'll get:
+
+```
+AssertionError: "piecesLeft" may not be negative.
+actual: -4
+```
+
+If you violate **multiple** conditions at once:
+
+```typescript
+const cake = new Cake(1);
+cake.bitesTaken = -1;
+cake.piecesLeft = 2;
+const failures = [];
+for (const failure of cake.getFailures())
+ failures.add(failure);
+console.log(failures.join("\n\n"));
+```
+
+You'll get:
+
+```
+"bitesTaken" may not be negative.
+actual: -1
+
+"piecesLeft" must be greater than 3.
+actual: 2
```
## Features
-* [Automatic message generation](wiki/Features.md#automatic-message-generation)
-* [Diffs provided whenever possible](wiki/Features.md#diffs-provided-whenever-possible)
-* [Assertion support](wiki/Features.md#assertion-support)
-* [Grouping nested requirements](wiki/Features.md#grouping-nested-requirements)
-* [String diff](wiki/Features.md#string-diff)
+This library offers the following features:
+
+* [Automatic message generation](docs/Features.md#automatic-message-generation) for validation failures
+* [Diffs provided whenever possible](docs/Features.md#diffs-provided-whenever-possible) to highlight the
+ differences between expected and actual values
+* [Zero overhead when assertions are disabled](docs/Features.md#assertion-support) for better performance
+* [Multiple validation failures](docs/Features.md#multiple-validation-failures) that report all the errors at
+ once
+* [Nested validations](docs/Features.md#nested-validations) that allow you to validate complex objects
+* [String diff](docs/Features.md#string-diff) that shows the differences between two strings
-## Getting Started
+## Entry Points
-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:
+Designed for discovery using your favorite IDE's auto-complete feature.
+The main entry points are:
-* [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)
+* [requireThat(value, name)](https://cowwoc.github.io/requirements.js/4.0/docs/api/module-DefaultRequirements.html#~requireThat)
+ for method preconditions.
+* [assertThat(value, name)](https://cowwoc.github.io/requirements.js/4.0/docs/api/module-DefaultRequirements.html#~assertThat)
+ for [class invariants, method postconditions and private methods](docs/Features.md#assertion-support).
+* [checkIf(value, name)](https://cowwoc.github.io/requirements.js/4.0/docs/api/module-DefaultRequirements.html#~checkIf)
+ for multiple failures and customized error handling.
-* [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)
+See the [API documentation](https://cowwoc.github.io/requirements.java/10.0/docs/api/) for more details.
## Best practices
-* Use `requireThat()` to verify pre-conditions of public APIs.
-* Use `assertThat()` to verify object invariants and method post-conditions.
- This results in excellent performance when assertions are disabled.
- Have your cake and eat it too!
+* Use `checkIf().elseGetMessages()` to return failure messages without throwing an exception.
+ This is the fastest validation approach, ideal for web services.
+* To enhance the clarity of failure messages, you should provide parameter names, even when they are optional.
+ In other words, favor `assert that(value, name)` over `assert that(value)`.
## Related Projects
diff --git a/build/LogFactory.mts b/build/LogFactory.mts
deleted file mode 100644
index 3f3ff88..0000000
--- a/build/LogFactory.mts
+++ /dev/null
@@ -1,49 +0,0 @@
-import {
- createLogger,
- format,
- Logger,
- transports
-} from "winston";
-
-// https://stackoverflow.com/a/63486530/14731
-const Reset = "\x1b[0m";
-const FgWhite = "\x1b[37m";
-const BgRed = "\x1b[41m";
-
-class LogFactory
-{
- /**
- * @param name the name of the logger
- */
- public static getLogger(name: string): Logger
- {
- return createLogger({
- transports: [new transports.Console()],
- format: format.combine(
- format(info =>
- {
- // https://github.com/winstonjs/winston/issues/1345#issuecomment-393853665
- info.level = info.level.toUpperCase();
- return info;
- })(),
- format.errors({stack: true}),
- format.prettyPrint(),
- format.colorize(),
- format.timestamp({format: "YYYY-MM-DD HH:mm:ss.SSS"}),
- format.printf(({
- timestamp,
- level,
- message,
- stack
- }) =>
- {
- if (stack)
- return `${timestamp} ${level} ${FgWhite + BgRed + name + Reset} - ${message}\n${stack}`;
- return `${timestamp} ${level} ${FgWhite + BgRed + name + Reset} - ${message}`;
- })
- )
- });
- }
-}
-
-export {LogFactory};
\ No newline at end of file
diff --git a/build/Project.mts b/build/Project.mts
index 2f2b0f2..b217e1d 100644
--- a/build/Project.mts
+++ b/build/Project.mts
@@ -3,9 +3,9 @@ import path from "path";
import {ESLint} from "eslint";
import TypeDoc from "typedoc";
import fs from "node:fs";
-import rollupCommonjs from "@rollup/plugin-commonjs";
+import _rollupCommonJs from "@rollup/plugin-commonjs";
import {nodeResolve as rollupNodeResolve} from "@rollup/plugin-node-resolve";
-import rollupTypescript from "@rollup/plugin-typescript";
+import _rollupTypescript, {type RollupTypescriptOptions} from "@rollup/plugin-typescript";
import {
type Plugin,
rollup
@@ -15,57 +15,53 @@ import ts from "typescript";
import {glob} from "glob";
import {minify} from "terser";
import {spawn} from "child_process";
-import {LogFactory} from "./LogFactory.mjs";
import {default as chokidar} from "chokidar";
-import eslintConfig from "../.eslintrc.mjs";
-import {Logger} from "winston";
-import {mode} from "./mode.mjs";
+import eslintConfig from "../eslint.config.mjs";
import parseArgs from "minimist";
-import _ from "lodash";
+import {
+ diary,
+ enable as enableDiaries
+} from "diary";
+import debounce from "lodash.debounce";
+import padStart from "lodash.padstart";
+// WORKAROUND: https://github.com/rollup/plugins/issues/1662#issuecomment-2337703188
+const rollupCommonJs = _rollupCommonJs as unknown as (options?: unknown) => Plugin;
+const rollupTypescript = _rollupTypescript as unknown as (options?: RollupTypescriptOptions) => Plugin;
class Project
{
- private readonly mode: string;
- private readonly log: Logger;
-
- constructor(mode: string)
- {
- // Use POSIX paths across all platforms
- const posixPath = url.fileURLToPath(import.meta.url).split(path.sep).join(path.posix.sep);
- const __filename = path.posix.basename(posixPath);
- this.log = LogFactory.getLogger(__filename);
- this.mode = mode;
- }
+ private static readonly outputDirectory = "target";
/**
- * @param sources the files to lint
- * @private
+ * @param sources - the files to lint
*/
private async lintTypescript(sources: string[])
{
- console.time("lintTypescript");
+ if (sources.length === 0)
+ return;
+ const startTime = performance.now();
const eslint = new ESLint({
baseConfig: eslintConfig,
- cache: true,
- "overrideConfig": {
- parserOptions: {
- debugLevel: false
- }
- }
+ cache: true
});
let results;
try
{
results = await eslint.lintFiles(sources);
+ const resultsMeta: ESLint.LintResultData =
+ {
+ cwd: process.cwd(),
+ rulesMeta: eslint.getRulesMetaForResults(results)
+ };
const formatter = await eslint.loadFormatter("stylish");
- const resultText = await formatter.format(results);
+ const resultText = await formatter.format(results, resultsMeta);
if (resultText)
- this.log.info(resultText);
+ log.info(resultText);
}
catch (error)
{
- this.log.error(`Lint error: ${error}`);
+ log.error(`Lint error: ${JSON.stringify(error, null, 2)}`);
throw error;
}
@@ -74,45 +70,47 @@ class Project
if (result.errorCount > 0)
throw new Error("lintTypescript failed");
}
- console.timeEnd("lintTypescript");
+ log.info(`lintTypescript: ${Project.timeElapsedSince(startTime)}`);
}
/**
* @param sources - the files to compile
- * @private
*/
private async bundleForNode(sources: string[])
{
- console.time("bundleForNode");
+ const startTime = performance.now();
try
{
- await Promise.all([this.lintTypescript(sources), this.compileTypescript(sources)]);
+ await this.lintTypescript(sources);
}
catch (error)
{
- this.log.error(`bundleForNode error: ${error}`);
+ log.error(`bundleForNode error: ${JSON.stringify(error, null, 2)}`);
throw error;
}
- console.timeEnd("bundleForNode");
+ this.compileTypescript(sources);
+ log.info(`bundleForNode: ${Project.timeElapsedSince(startTime)}`);
}
/**
- * @param sources the files to compile
- * @private
+ * @param sources - the files to compile
*/
- private async compileTypescript(sources: string[])
+ private compileTypescript(sources: string[])
{
- console.time("compileTypescript");
+ const startTime = performance.now();
// Example of compiling using API: https://gist.github.com/jeremyben/4de4fdc40175d0f76892209e00ece98f
const cwd = process.cwd();
- const configFile = ts.findConfigFile(cwd, ts.sys.fileExists, "tsconfig.json");
+ const configFile = ts.findConfigFile(cwd, filename => ts.sys.fileExists(filename), "tsconfig.json");
if (!configFile)
throw Error("tsconfig.json not found");
- const {config} = ts.readConfigFile(configFile, ts.sys.readFile);
- config.compilerOptions.outDir = "target/publish/node/";
+ // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+ const {config} = ts.readConfigFile(configFile, path => ts.sys.readFile(path));
+ /* eslint-disable @typescript-eslint/no-unsafe-member-access */
+ config.compilerOptions.outDir = `${Project.outputDirectory}/publish/node/`;
config.compilerOptions.declaration = true;
config.include = undefined;
config.files = sources;
+ /* eslint-enable @typescript-eslint/no-unsafe-member-access */
const {
options,
@@ -135,26 +133,22 @@ class Project
{
const formatHost: ts.FormatDiagnosticsHost = {
getCanonicalFileName: (path) => path,
- getCurrentDirectory: ts.sys.getCurrentDirectory,
+ getCurrentDirectory: () => ts.sys.getCurrentDirectory(),
getNewLine: () => ts.sys.newLine
};
const message = ts.formatDiagnostics(allDiagnostics, formatHost);
- this.log.warn(message);
+ log.warn(message);
}
if (emitSkipped)
throw new Error("compileTypescript() failed");
- console.timeEnd("compileTypescript");
+ log.info(`compileTypescript: ${Project.timeElapsedSince(startTime)}`);
}
- public async bundleForBrowser()
+ private async bundleForBrowser()
{
- console.time("bundleForBrowser");
-
- // Need to cast plugins to Function due to bug in type definitions.
- // WORKAROUND: https://github.com/algolia/algoliasearch-client-javascript/issues/1431#issuecomment-1568529321
+ const startTime = performance.now();
const plugins: Plugin[] = [
- rollupCommonjs,
- (rollupTypescript as unknown as Function)({
+ rollupTypescript({
"module": "ES2022",
"moduleResolution": "bundler"
}),
@@ -163,7 +157,7 @@ class Project
mainFields: ["module"],
preferBuiltins: true
}),
- (rollupCommonjs as unknown as Function)({include: "node_modules/**"})
+ rollupCommonJs({include: "node_modules/**"})
];
try
@@ -187,30 +181,27 @@ class Project
await bundle.write(
{
sourcemap: true,
- dir: "target/publish/browser"
+ dir: `${Project.outputDirectory}/publish/browser`
});
- if (this.mode === "RELEASE")
- await this.minifyBrowserSources();
+ await this.minifyBrowserSources();
}
catch (error)
{
- this.log.error(`bundleForBrowser error: ${error}`);
+ log.error(`bundleForBrowser error: ${JSON.stringify(error, null, 2)}`);
throw error;
}
- console.timeEnd("bundleForBrowser");
+ log.info(`bundleForBrowser: ${Project.timeElapsedSince(startTime)}`);
}
/**
* Minify the source-code.
- *
- * @private
*/
private async minifyBrowserSources()
{
- console.time("minifyBrowserSources");
- const targetDirectory = "target/publish/browser/";
+ const startTime = performance.now();
+ const targetDirectory = `${Project.outputDirectory}/publish/browser/`;
- const sourceFiles = glob.sync("target/publish/browser/index.js");
+ const sourceFiles = glob.sync(`${Project.outputDirectory}/publish/browser/index.js`);
const pathToCode: { [name: string]: string } = {};
for (const file of sourceFiles)
@@ -222,13 +213,11 @@ class Project
ecma: 2020,
compress:
{
- /* eslint-disable camelcase */
drop_console: true,
global_defs:
{
"@alert": "console.log"
}
- /* eslint-enable camelcase */
},
sourceMap: {
filename: "index.min.mjs.map"
@@ -240,13 +229,13 @@ class Project
fs.writeFileSync(targetDirectory + "index.min.mjs", code);
fs.writeFileSync(targetDirectory + "index.min.mjs.map", map);
- console.timeEnd("minifyBrowserSources");
+ log.info(`minifyBrowserSources: ${Project.timeElapsedSince(startTime)}`);
}
public async generateDocumentation()
{
- console.time("generateDocumentation");
- const targetDirectory = "target/apidocs/";
+ const startTime = performance.now();
+ const targetDirectory = `${Project.outputDirectory}/apidocs/`;
const app = await TypeDoc.Application.bootstrapWithPlugins({}, [
new TypeDoc.TypeDocReader(),
@@ -262,17 +251,18 @@ class Project
await app.generateDocs(project, targetDirectory);
if (app.logger.hasErrors())
throw new Error("generateDocumentation failed");
- console.timeEnd("generateDocumentation");
+ log.info(`generateDocumentation: ${Project.timeElapsedSince(startTime)}`);
}
/**
- * @param sources - the resources in the project
- * @private
+ * @param sources - the files to bundle
*/
- public async bundleResources(sources: string[])
+ private async bundleResources(sources: string[])
{
- console.time("bundleResources");
- const targetDirectory = "target/publish/";
+ if (sources.length === 0)
+ return;
+ const startTime = performance.now();
+ const targetDirectory = `${Project.outputDirectory}/publish/`;
if (!fs.existsSync(targetDirectory))
fs.mkdirSync(targetDirectory, {recursive: true});
let promises: Promisename is null
- * @throws RangeError if name is empty
- */
- contains(element: E, name?: string): ArrayValidatorname is null
- * @throws RangeError if name is empty
- */
- containsExactly(expected: E[], name?: string): ArrayValidatorname is null
- * @throws RangeError if name is empty
- */
- containsAny(expected: E[], name?: string): ArrayValidatorname is null
- * @throws RangeError if name is empty
- */
- containsAll(expected: E[], name?: string): ArrayValidatorname is null
- * @throws RangeError if name is empty
- */
- doesNotContain(element: E, name?: string): ArrayValidatorname is null
- * @throws RangeError if name is empty
- */
- doesNotContainAny(elements: E[], name?: string): ArrayValidatorname is null
- * @throws RangeError if name is empty
- */
- doesNotContainAll(elements: E[], name?: string): ArrayValidatorconsumer is not set
- */
- lengthConsumer(consumer: (length: NumberValidator) => void): ArrayValidatorname is null
- * @throws RangeError if name is empty.
- * If the array does not contain element.
- */
- contains(element: E, name?: string): ArrayVerifiername is null.
- * If expected is not an Array.
- * @throws RangeError if name is empty.
- * If the array is missing any elements in expected.
- * If the array contains elements not found in expected.
- */
- containsExactly(expected: E[], name?: string): ArrayVerifiername is null.
- * If expected is not an Array.
- * @throws RangeError if name is empty.
- * If the array is missing any elements in expected.
- * If the array contains elements not found in expected.
- */
- containsAny(expected: E[], name?: string): ArrayVerifiername is null.
- * If expected is not an Array
- * @throws RangeError if name is empty.
- * If the array does not contain all of expected.
- */
- containsAll(expected: E[], name?: string): ArrayVerifiername is null
- * @throws RangeError if name is empty.
- * If the array contains element.
- */
- doesNotContain(element: E, name?: string): ArrayVerifiername is null.
- * If elements is not an Array.
- * @throws RangeError if name is empty.
- * If the array contains any of elements.
- */
- doesNotContainAny(elements: E[], name?: string): ArrayVerifiername is null.
- * If elements is not an Array.
- * @throws RangeError if name is empty.
- * If the array contains all of elements.
- */
- doesNotContainAll(elements: E[], name?: string): ArrayVerifierconsumer is not set
- */
- lengthConsumer(consumer: (actual: NumberVerifier) => void): ArrayVerifierboolean.
- *
- * Verifier and Validator methods are equivalent.
- * Validators return validation failures through the
- * {@link ExtensibleObjectValidator.getFailures | getFailures()} method, while Verifiers throw them as
- * exceptions.
- *
- * All methods (except those found in {@link ObjectValidator}) assume that the actual value is not null.
- */
-interface BooleanValidator extends ExtensibleObjectValidatorboolean.
- *
- * All methods (except those found in {@link ObjectVerifier}) assume that the actual value is not null.
- */
-interface BooleanVerifier extends ExtensibleObjectVerifier
- * All methods (except those found in {@link ObjectVerifier}) assume that the actual value is not null.
- *
- * @typeParam T - the type of the class
- */
-interface ClassVerifier
- * Please note that
+ * There are three kinds of validators:
+ *
+ */
+const DELEGATE = new JavascriptValidatorsImpl(MainApplicationScope.INSTANCE, Configuration.DEFAULT);
+
+/**
+ * Validates the state of a number.
+ *
+ * The returned validator throws an error immediately if a validation fails.
+ *
+ * @typeParam T - the type the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns a verifier
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function requireThatNumber
+ * The returned validator throws an error immediately if a validation fails.
+ *
+ * @typeParam T - the type the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns a verifier
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function requireThatBoolean
+ * The returned validator throws an exception immediately if a validation fails. This exception is then
+ * converted into an {@link AssertionError}. Exceptions unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type the value
+ * @typeParam E - the type elements in the array
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function requireThatArray
+ * The returned validator throws an exception immediately if a validation fails. This exception is then
+ * converted into an {@link AssertionError}. Exceptions unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type the value
+ * @typeParam E - the type elements in the set
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function requireThatSet
+ * The returned validator throws an exception immediately if a validation fails. This exception is then
+ * converted into an {@link AssertionError}. Exceptions unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type the value
+ * @typeParam K - the type of keys in the map
+ * @typeParam V - the type of values in the map
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function requireThatMap
+ * The returned validator throws an exception immediately if a validation fails. This exception is then
+ * converted into an {@link AssertionError}. Exceptions unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function requireThatString
+ * The returned validator throws an exception immediately if a validation fails. This exception is then
+ * converted into an {@link AssertionError}. Exceptions unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function requireThat
+ * The returned validator throws an exception immediately if a validation fails. This exception is then
+ * converted into an {@link AssertionError}. Exceptions unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function assertThatNumber
+ * The returned validator throws an exception immediately if a validation fails. This exception is then
+ * converted into an {@link AssertionError}. Exceptions unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function assertThatBoolean
+ * The returned validator throws an exception immediately if a validation fails. This exception is then
+ * converted into an {@link AssertionError}. Exceptions unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type the value
+ * @typeParam E - the type elements in the array
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function assertThatArray
+ * The returned validator throws an exception immediately if a validation fails. This exception is then
+ * converted into an {@link AssertionError}. Exceptions unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type the value
+ * @typeParam E - the type elements in the set
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function assertThatSet
+ * The returned validator throws an exception immediately if a validation fails. This exception is then
+ * converted into an {@link AssertionError}. Exceptions unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type the value
+ * @typeParam K - the type of keys in the map
+ * @typeParam V - the type of values in the map
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function assertThatMap
+ * The returned validator throws an exception immediately if a validation fails. This exception is then
+ * converted into an {@link AssertionError}. Exceptions unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function assertThatString
+ * The returned validator throws an exception immediately if a validation fails. This exception is then
+ * converted into an {@link AssertionError}. Exceptions unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function assertThat
+ * The returned validator throws an error immediately if a validation fails.
+ *
+ * @typeParam T - the type the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function checkIfNumber
+ * The returned validator throws an error immediately if a validation fails.
+ *
+ * @typeParam T - the type the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function checkIfBoolean
+ * The returned validator throws an error immediately if a validation fails.
+ *
+ * @typeParam T - the type the value
+ * @typeParam E - the type elements in the array
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function checkIfArray
+ * The returned validator throws an error immediately if a validation fails.
+ *
+ * @typeParam T - the type the value
+ * @typeParam E - the type elements in the array or set
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function checkIfSet
+ * The returned validator throws an error immediately if a validation fails.
+ *
+ * @typeParam T - the type the value
+ * @typeParam K - the type of keys in the map
+ * @typeParam V - the type of values in the map
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function checkIfMap
+ * The returned validator throws an error immediately if a validation fails.
+ *
+ * @typeParam T - the type the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function checkIfString
+ * The returned validator throws an error immediately if a validation fails.
+ *
+ * @typeParam T - the type the value
+ * @typeParam E - the type elements in the array or set
+ * @typeParam K - the type of keys in the map
+ * @typeParam V - the type of values in the map
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` is empty
+ */
+function checkIf
+ * ```console
+ * Password may not be empty
+ * username: john.smith
+ * ```
+ *
+ * @returns an unmodifiable map from each entry's name to its value
+ */
+function getContext()
+{
+ return DELEGATE.getContext();
+}
+
+/**
+ * Sets the contextual information for validators created by this factory.
+ *
+ * This method adds contextual information to error messages. The contextual information is stored as
+ * key-value pairs in a map. Values set by this method may be overridden by
+ * {@link ValidatorComponent.withContext}.
+ *
+ * @param value - the value of the entry
+ * @param name - the name of an entry
+ * @returns the underlying validator factory
+ * @throws NullPointerError if `name` is not a string
+ */
+function withContext(value: unknown, name: string)
+{
+ return DELEGATE.withContext(value, name);
+}
+
+/**
+ * Removes the contextual information of validators created by this factory.
+ *
+ * @param name - the parameter name
+ * @returns the underlying validator factory
+ * @throws NullPointerError if `name` is not a string
+ * @throws IllegalArgumentError if `name` contains leading or trailing whitespace, or is
+ * empty
+ */
+function removeContext(name: string)
+{
+ return DELEGATE.removeContext(name);
+}
+
+/**
+ * Returns the global configuration shared by all validators.
+ *
+ * NOTE: Updating this configuration affects existing and new validators.
+ *
+ * @returns the global configuration updater
+ */
+function globalConfiguration()
+{
+ return DELEGATE.getGlobalConfiguration();
+}
+
+export {
+ requireThatNumber,
+ requireThatBoolean,
+ requireThatArray,
+ requireThatSet,
+ requireThatMap,
+ requireThatString,
+ requireThat,
+ assertThatNumber,
+ assertThatBoolean,
+ assertThatArray,
+ assertThatSet,
+ assertThatMap,
+ assertThatString,
+ assertThat,
+ checkIfNumber,
+ checkIfBoolean,
+ checkIfArray,
+ checkIfSet,
+ checkIfMap,
+ checkIfString,
+ checkIf,
+ updateConfiguration,
+ getContext,
+ withContext,
+ removeContext,
+ globalConfiguration
+};
\ No newline at end of file
diff --git a/src/DefaultRequirements.mts b/src/DefaultRequirements.mts
deleted file mode 100644
index 4041f66..0000000
--- a/src/DefaultRequirements.mts
+++ /dev/null
@@ -1,217 +0,0 @@
-import type {
- GlobalConfiguration,
- ObjectValidator,
- ObjectVerifier,
- StringValidator,
- NumberValidator,
- ClassValidator,
- ArrayValidator,
- SetValidator,
- MapValidator,
- StringVerifier,
- NumberVerifier,
- ClassVerifier,
- ArrayVerifier,
- SetVerifier,
- MapVerifier,
- ClassConstructor,
- BooleanValidator,
- BooleanVerifier,
- AnythingButClassConstructor
-} from "./internal/internal.mjs";
-import {
- Requirements,
- Objects,
- ArrayValidatorImpl,
- Pluralizer,
- SetValidatorImpl,
- ClassValidatorImpl,
- ObjectValidatorImpl,
- Configuration,
- MainGlobalConfiguration,
- ArrayVerifierImpl,
- SetVerifierImpl,
- MapVerifierImpl,
- MapValidatorImpl,
- ClassVerifierImpl,
- ObjectVerifierImpl,
- BooleanVerifierImpl,
- BooleanValidatorImpl,
- StringVerifierImpl,
- StringValidatorImpl,
- NumberVerifierImpl,
- NumberValidatorImpl
-} from "./internal/internal.mjs";
-
-const typedocWorkaround: null | GlobalConfiguration = null;
-// noinspection PointlessBooleanExpressionJS
-if (typedocWorkaround !== null)
- console.log("WORKAROUND: https://github.com/microsoft/tsdoc/issues/348");
-
-/**
- * Verifies the requirements of an object.
- *
- * @typeParam T - the type the actual value
- * @param actual - the actual value
- * @param name - the name of the value
- * @returns a verifier
- * @throws TypeError if
- * Note: Verifiers inherit from the global configuration at instantiation time. Their
- * {@link Configuration | configuration} is not affected by subsequent changes to the global configuration.
- *
- * However, updating settings not found in {@link Configuration} (such as
- * {@link GlobalConfiguration.withTerminalEncoding | withTerminalEncoding(TerminalEncoding)}) will impact the
- * behavior of existing verifiers.
- *
- * By default, {@link GlobalConfiguration.assertionsAreEnabled | assertionsAreEnabled} is
- * This feature can be used to force the use of colors even when their support is not detected.
+ * This can be used to force the use of ANSI colors when their support is not detected.
*
* @param encoding - the type of encoding that the terminal supports
* @returns this
- * @throws TypeError if
- * This feature can be used to override the default terminal width when it cannot be auto-detected.
- *
- * @param width - the terminal width in characters
- * @returns this
- * @throws TypeError if
- * This feature can be used to force the use of colors even when their support is not detected.
- *
- * @param encoding - the type of encoding that the terminal supports
- * @throws TypeError if
- * This feature can be used to override the default terminal width when it cannot be auto-detected.
- *
- * @param width - the terminal width in characters
- * @throws TypeError if
- * All methods (except those found in {@link ObjectVerifier}) assume that the actual value is not null.
- */
-interface InetAddressVerifier extends ExtensibleObjectVerifier
+ * The returned validator throws an error immediately if a validation fails. This error is then
+ * converted into an {@link AssertionError}. Errors unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type of the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns a validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` contains whitespace or is empty
+ */
+ assertThatNumber
+ * The returned validator throws an error immediately if a validation fails. This error is then
+ * converted into an {@link AssertionError}. Errors unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type of the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns a validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` contains whitespace or is empty
+ */
+ assertThatBoolean
+ * The returned validator throws an error immediately if a validation fails. This error is then
+ * converted into an {@link AssertionError}. Errors unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type of the value
+ * @typeParam E - the type of elements in the collection
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns a validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` contains whitespace or is empty
+ */
+ assertThatArray
+ * The returned validator throws an error immediately if a validation fails. This error is then
+ * converted into an {@link AssertionError}. Errors unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type of the value
+ * @typeParam E - the type of elements in the set
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns a validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` contains whitespace or is empty
+ */
+ assertThatSet
+ * The returned validator throws an error immediately if a validation fails. This error is then
+ * converted into an {@link AssertionError}. Errors unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type of the value
+ * @typeParam K - the type of keys in the map
+ * @typeParam V - the type of values in the map
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns a validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` contains whitespace or is empty
+ */
+ assertThatMap
+ * The returned validator throws an error immediately if a validation fails. This error is then
+ * converted into an {@link AssertionError}. Errors unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type of the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns a validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` contains whitespace or is empty
+ */
+ assertThatString
+ * The returned validator throws an error immediately if a validation fails. This error is then
+ * converted into an {@link AssertionError}. Errors unrelated to validation failures are not converted.
+ *
+ * @typeParam T - the type of the value
+ * @param value - the value
+ * @param name - the name of the value
+ * @returns a validator for the value
+ * @throws TypeError if `name` is `undefined` or `null`
+ * @throws RangeError if `name` contains whitespace or is empty
+ */
+ assertThattype
- */
- isSupertypeOftype
- */
- isSubtypeOftrue if assertThat() should invoke
- * requireThat(). false if assertThat() should do nothing. If
- * undefined defaults to globalConfiguration.assertionsAreEnabled().
- * @param diffEnabled - (optional) true if exceptions should show the difference between the actual and
- * expected values. If undefined defaults to globalConfiguration.diffEnabled().
- * @param typeToStringConverter - (optional) a map from the typeof of a value to a function
- * that converts the value to a string
- * @throws TypeError if context or one of its elements are not an array. If the nested array
- * contains less or more than 2 elements. If the keys nested in the context array are not strings.
- * @throws RangeError if the elements nested in the context array are undefined, null, or are empty
- */
- constructor(globalConfiguration: GlobalConfiguration,
- context = new MapassertThat() should invoke requireThat().
- *
- * @returns true if assertThat() should delegate to requireThat().
- * false if it shouldn't do anything.
- */
- assertionsAreEnabled()
- {
- return this.assertionsEnabled;
- }
-
- /**
- * Indicates that assertThat() should invoke requireThat().
- *
- * @returns this
- */
- withAssertionsEnabled()
- {
- if (!this.assertionsEnabled)
- this.assertionsEnabled = true;
- return this;
- }
-
- /**
- * Indicates that assertThat() shouldn't do anything.
- *
- * @returns this
- */
- withAssertionsDisabled()
- {
- if (this.assertionsEnabled)
- this.assertionsEnabled = false;
- return this;
- }
-
- /**
- * Indicates if exceptions should show the difference between the actual and expected values.
- *
- * @returns true by default
- */
- isDiffEnabled()
- {
- return this.diffEnabled;
- }
-
- /**
- * Indicates that exceptions should show the difference between the actual and expected values.
- *
- * @returns this
- */
- withDiff()
- {
- if (!this.diffEnabled)
- this.diffEnabled = true;
- return this;
- }
-
- /**
- * Indicates that exceptions should not show the difference between the actual and expected values.
- *
- * @returns this
- */
- withoutDiff()
- {
- if (this.diffEnabled)
- this.diffEnabled = false;
- return this;
- }
-
- /**
- * @returns a map of key-value pairs to append to the exception message
- * @see #putContext
- */
- getContext()
- {
- return this.context;
- }
-
- /**
- * Adds or updates contextual information associated with the exception message.
- *
- * @param name - the name of the parameter
- * @param value - the value of the parameter
- * @returns this
- * @throws TypeError if key is not a string
- * @see #getContext
- */
- putContext(name: string, value: unknown)
- {
- Objects.requireThatStringIsNotEmpty(name, "name");
- this.context.set(name, value);
- return this;
- }
-
- /**
- * Removes contextual information associated with the exception message.
- *
- * @param name - the name of the parameter
- * @returns this
- * @throws TypeError if name is null
- */
- removeContext(name: string)
- {
- Objects.requireThatStringIsNotEmpty(name, "name");
- this.context.delete(name);
- return this;
- }
-
- /**
- * Returns the String representation of an object. By default, custom handlers are provided for
- * arrays, number and Set.
- *
- * @param value - a value
- * @returns the String representation of the value
- * @see #withStringConverter
- */
- convertToString(value: unknown)
- {
- const valueInfo = Objects.getTypeInfo(value);
- let converter = this.typeToStringConverter.get(valueInfo.type);
- if (!converter)
- converter = (value2: unknown) => Objects.toString(value2);
- return converter(value);
- }
-
- /**
- * Indicates that a function should be used to convert a value to a string.
- * type must be an exact match, subclasses do not inherit converters from
- * their superclass.
- *
- * @param type - the
- * typeof
- * of the type being converted
- * @param converter - a function that converts an object of the specified type to a string
- * @returns this
- * @throws RangeError if any of the parameters are null
- */
- withStringConverter(type: string, converter: (input: unknown) => string)
- {
- Objects.assertThatTypeOf(type, "type", "string");
- Objects.assertThatTypeOf(converter, "converter", "function");
- this.typeToStringConverter.set(type, converter);
- return this;
- }
-
- /**
- * Indicates that the default converter should be used for type.
- *
- * @param type - the
- * typeof
- * of the type being converted
- * @returns this
- * @throws RangeError if type is null
- */
- withoutStringConverter(type: string)
- {
- Objects.assertThatTypeOf(type, "type", "string");
- this.typeToStringConverter.delete(type);
- return this;
- }
-
- /**
- * Returns the global configuration.
- *
- * @returns the global configuration associated with this object
- */
- getGlobalConfiguration()
- {
- return this.globalConfiguration;
- }
-}
-
-export {Configuration};
\ No newline at end of file
diff --git a/src/ContextLine.mts b/src/ContextLine.mts
deleted file mode 100644
index 3b01c5f..0000000
--- a/src/ContextLine.mts
+++ /dev/null
@@ -1,48 +0,0 @@
-import type {Configuration} from "./internal/internal.mjs";
-import {Objects} from "./internal/internal.mjs";
-
-/**
- * A line item in an exception context.
- */
-class ContextLine
-{
- /**
- * The instance configuration.
- */
- public readonly config: Configuration;
- /**
- * The key associated with the value (empty string is absent).
- */
- public readonly key: string;
- /**
- * A value.
- */
- public readonly value: unknown;
-
- /**
- * Creates a new line.
- *
- * @param configuration - the instance configuration
- * @param key - the key associated with the value (empty string if absent)
- * @param value - a value
- * @throws TypeError if the key is not a string
- */
- constructor(configuration: Configuration, key: string, value: unknown)
- {
- Objects.assertThatTypeOf(key, "key", "string");
- this.config = configuration;
- this.key = key;
- this.value = value;
- }
-
- toString(): string
- {
- let result = "";
- if (this.key.length !== 0)
- result += this.key + ":";
- result += this.config.convertToString(this.value);
- return result;
- }
-}
-
-export {ContextLine};
\ No newline at end of file
diff --git a/src/DefaultJavascriptValidators.mts b/src/DefaultJavascriptValidators.mts
new file mode 100644
index 0000000..5cc81cb
--- /dev/null
+++ b/src/DefaultJavascriptValidators.mts
@@ -0,0 +1,541 @@
+import {
+ type BooleanValidator,
+ type StringValidator,
+ type NumberValidator,
+ type ArrayValidator,
+ type SetValidator,
+ type MapValidator,
+ type UnknownValidator,
+ Configuration,
+ JavascriptValidatorsImpl,
+ MainApplicationScope,
+ type ConfigurationUpdater,
+ type ValidatorComponent,
+ JavascriptValidators,
+ AssertionError
+} from "./internal/internal.mjs";
+
+const typedocWorkaround: null | ValidatorComponent
+ *
+ * name is null
- * @throws RangeError if name is empty
- */
-function requireThat(actual: boolean, name: string): BooleanVerifier;
-function requireThat(actual: string, name: string): StringVerifier;
-function requireThat(actual: number, name: string): NumberVerifier;
-function requireThatname is null
- * @throws RangeError if name is empty
- * @see {@link GlobalConfiguration.assertionsAreEnabled | GlobalConfiguration.assertionsAreEnabled}
- */
-function validateThat(actual: boolean, name: string): BooleanValidator;
-function validateThat(actual: string, name: string): StringValidator;
-function validateThat(actual: number, name: string): NumberValidator;
-function validateThatname is null
- * @throws RangeError if name is empty
- * @see {@link GlobalConfiguration.assertionsAreEnabled | GlobalConfiguration.assertionsAreEnabled}
- */
-function assertThat(requirements: (requirements: Requirements) => void)
-{
- Objects.requireThatValueIsDefinedAndNotNull(requirements, "requirements");
- const config = new Configuration(MainGlobalConfiguration.INSTANCE);
- if (config.assertionsAreEnabled())
- requirements(new Requirements());
-}
-
-/**
- * Verifies requirements only if assertions are enabled.
- *
- * By default, assertions are disabled.
- * See {@link GlobalConfiguration.assertionsAreEnabled | GlobalConfiguration.assertionsAreEnabled} to change
- * the default.
- *
- * @param requirements - the requirements to verify
- * @returns the value returned by requirements
- * @throws TypeError if name is null
- * @throws RangeError if name is empty
- * @see {@link GlobalConfiguration.assertionsAreEnabled | GlobalConfiguration.assertionsAreEnabled}
- */
-function assertThatAndReturn(requirements: (requirements: Requirements) => void)
-{
- Objects.requireThatValueIsDefinedAndNotNull(requirements, "requirements");
- const config = new Configuration(MainGlobalConfiguration.INSTANCE);
- if (config.assertionsAreEnabled())
- return requirements(new Requirements());
- return undefined;
-}
-
-export
-{
- requireThat,
- validateThat,
- assertThat,
- assertThatAndReturn
-};
\ No newline at end of file
diff --git a/src/GlobalConfiguration.mts b/src/GlobalConfiguration.mts
index 91bbc88..3de165f 100644
--- a/src/GlobalConfiguration.mts
+++ b/src/GlobalConfiguration.mts
@@ -1,130 +1,40 @@
+/*
+ * Copyright (c) 2019 Gili Tzabari
+ * Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
+ */
import type {TerminalEncoding} from "./internal/internal.mjs";
/**
- * The global configuration inherited by all verifiers.
- * false
- * and {@link GlobalConfiguration.isDiffEnabled | isDiffEnabled} is true.
+ * The configuration shared by all validators. Changes apply to existing or new validators.
*/
interface GlobalConfiguration
{
/**
- * Indicates whether assertThat() should invoke requireThat().
- *
- * @returns true if assertThat() should delegate to requireThat(); false
- * if it shouldn't do anything
- */
- assertionsAreEnabled(): boolean;
-
- /**
- * Indicates that assertThat() should invoke requireThat().
- *
- * @returns this
- */
- withAssertionsEnabled(): GlobalConfiguration;
-
- /**
- * Indicates that assertThat() shouldn't do anything.
- *
- * @returns this
- */
- withAssertionsDisabled(): GlobalConfiguration;
-
- /**
- * Indicates if exceptions should show the difference between the actual and expected values.
- *
- * @returns true by default
- * @see #withDiff()
- * @see #withoutDiff()
- */
- isDiffEnabled(): boolean;
-
- /**
- * Indicates that exceptions should show the difference between the actual and expected values.
- *
- * @returns this
- * @see #isDiffEnabled()
- */
- withDiff(): GlobalConfiguration;
-
- /**
- * Indicates that exceptions should not show the difference between the actual and expected values.
+ * Returns the encoding supported by the terminal.
*
- * @returns this
- * @see #isDiffEnabled()
- */
- withoutDiff(): GlobalConfiguration;
-
- /**
- * Returns the color encodings supported by the terminal.
- *
- * @returns the encodings supported by the terminal (defaults to the auto-detected encoding)
- * @see #withTerminalEncoding(TerminalEncoding)
- * @see #withDefaultTerminalEncoding()
+ * @returns the encoding supported by the terminal
*/
- listTerminalEncodings(): TerminalEncoding[];
+ supportedTerminalEncodings(): Setencoding is null
- * @see #.withDefaultTerminalEncoding
- */
- withTerminalEncoding(encoding: TerminalEncoding): GlobalConfiguration;
-
- /**
- * Returns the current terminal width.
- *
- * @returns the terminal width in characters (defaults to the auto-detected width)
- */
- getTerminalWidth(): number;
-
- /**
- * Indicates that the terminal width should be auto-detected.
- *
- * @returns this
- * @see #.withTerminalWidth
+ * @throws TypeError if `encoding` is `undefined` or `null`
*/
- withDefaultTerminalWidth(): GlobalConfiguration;
+ terminalEncoding(encoding: TerminalEncoding): GlobalConfiguration;
- /**
- * Indicates the width that the terminal should use.
- * width is null
- * @throws RangeError if width is zero or negative
- * @see #.withDefaultTerminalWidth
- */
- withTerminalWidth(width: number): GlobalConfiguration;
+ terminalEncoding(encoding?: TerminalEncoding): TerminalEncoding | GlobalConfiguration;
}
-export {type GlobalConfiguration};
\ No newline at end of file
+export type {GlobalConfiguration};
\ No newline at end of file
diff --git a/src/GlobalRequirements.mts b/src/GlobalRequirements.mts
deleted file mode 100644
index c9c62fa..0000000
--- a/src/GlobalRequirements.mts
+++ /dev/null
@@ -1,153 +0,0 @@
-import type {TerminalEncoding} from "./internal/internal.mjs";
-import {MainGlobalConfiguration} from "./internal/internal.mjs";
-
-const delegate = MainGlobalConfiguration.INSTANCE;
-
-/**
- * The configuration shared by all verifiers.
- */
-class GlobalRequirements
-{
- /**
- * Indicates whether assertThat() should invoke requireThat().
- *
- * @returns true if assertThat() should delegate to requireThat(); false
- * if it shouldn't do anything
- */
- static assertionsAreEnabled()
- {
- return delegate.assertionsAreEnabled();
- }
-
- /**
- * Indicates that assertThat() should invoke requireThat().
- */
- static withAssertionsEnabled()
- {
- delegate.withAssertionsEnabled();
- }
-
- /**
- * Indicates that assertThat() shouldn't do anything.
- */
- static withAssertionsDisabled()
- {
- delegate.withAssertionsDisabled();
- }
-
- /**
- * Indicates if exceptions should show the difference between the actual and expected values.
- *
- * @returns true by default
- * @see #withDiff()
- * @see #withoutDiff()
- */
- static isDiffEnabled()
- {
- return delegate.isDiffEnabled();
- }
-
- /**
- * Indicates that exceptions should show the difference between the actual and expected values.
- *
- * @see #isDiffEnabled()
- */
- static withDiff()
- {
- delegate.withDiff();
- }
-
- /**
- * Indicates that exceptions should not show the difference between the actual and expected values.
- *
- * @see #isDiffEnabled()
- */
- static withoutDiff()
- {
- delegate.withoutDiff();
- }
-
- /**
- * Returns the color encodings supported by the terminal.
- *
- * @returns the encodings supported by the terminal (defaults to the auto-detected
- * encoding)
- * @see #withTerminalEncoding(TerminalEncoding)
- * @see #withDefaultTerminalEncoding()
- */
- static listTerminalEncodings()
- {
- return delegate.listTerminalEncodings();
- }
-
- /**
- * Returns the current terminal encoding.
- *
- * @returns the current terminal encoding (defaults to the auto-detected encoding)
- */
- static getTerminalEncoding()
- {
- return delegate.getTerminalEncoding();
- }
-
- /**
- * Indicates that the terminal encoding should be auto-detected.
- *
- * @see #.withTerminalEncoding
- */
- static withDefaultTerminalEncoding()
- {
- delegate.withDefaultTerminalWidth();
- }
-
- /**
- * Indicates the type of encoding that the terminal supports.
- * encoding is null
- * @see #.withDefaultTerminalEncoding
- */
- static withTerminalEncoding(encoding: TerminalEncoding)
- {
- delegate.withTerminalEncoding(encoding);
- }
-
- /**
- * Returns the current terminal width.
- *
- * @returns the terminal width in characters (defaults to the auto-detected width)
- */
- static getTerminalWidth()
- {
- return delegate.getTerminalWidth();
- }
-
- /**
- * Indicates that the terminal width should be auto-detected.
- *
- * @see #.withTerminalWidth
- */
- static withDefaultTerminalWidth()
- {
- delegate.withDefaultTerminalWidth();
- }
-
- /**
- * Indicates the width that the terminal should use.
- * width is null
- * @throws RangeError if width is zero or negative
- * @see #.withDefaultTerminalWidth
- */
- withTerminalWidth(width: number)
- {
- delegate.withTerminalWidth(width);
- }
-}
-
-export {GlobalRequirements};
\ No newline at end of file
diff --git a/src/InetAddressValidator.mts b/src/InetAddressValidator.mts
deleted file mode 100644
index c8f69d1..0000000
--- a/src/InetAddressValidator.mts
+++ /dev/null
@@ -1,43 +0,0 @@
-import type {ExtensibleObjectValidator} from "./internal/internal.mjs";
-
-/**
- * Validates the requirements of an IP address or hostname.
- *
- * Verifier and Validator methods are equivalent.
- * Validators return validation failures through the
- * {@link ExtensibleObjectValidator.getFailures | getFailures()} method, while Verifiers throw them as
- * exceptions.
- *
- * All methods (except those found in {@link ObjectValidator}) assume that the actual value is not null.
- */
-interface InetAddressValidator extends ExtensibleObjectValidator