Rewrite library, tests, and examples

Changed:
- Replaced terribly underperformant—and too clever—throw/catch pattern with a fallback/middleware pattern.
- Replaced `FilterException`, `BadValueException`, and `TypeMismatchException` with single `FilterError`.
- Replaced `createFilterResolver()` with `createFilterMiddleware()` to use composite filter functions instead of iterating them for each attribute.
- Renamed `createFilterFunction()` with `createFilterCallable()` for a more versatile name.
- Renamed `createFilterArray()` with `createFilterList()` for a more generic name.
- Altered `filterList()` to expect a string instead of relying on a try/catch.
- Removed obsolete `createFilterChain()`.
- Added helper function `filterFallback()` to resolve the fallback argument with support for the middleware pattern.
- Integrated `filterFallback()` into `filterStringable()`, `filterToken()`, `filterValue()`, and `filterList()`.
- Renamed module file for `createOrderedAttributesComparator()`.
- Update benchmarks to reflect significant performance improvements.

Author: mcaskill

README.md

@@ -120,16 +120,16 @@ implementations against a few simple use cases that cover most HTML attributes:
 
 ```
 # Set #1
-  Original  x 1,321,465 ops/sec ±0.16% (98 runs sampled)
-  Current   x 13,828 ops/sec ±0.35% (87 runs sampled)
+  Original  x 1,327,189 ops/sec ±0.14% (94 runs sampled)
+  Current   x 995,463 ops/sec ±0.09% (98 runs sampled)
 
 # Set #2
-  Original  x 1,640,239 ops/sec ±0.13% (101 runs sampled)
-  Current   x 20,588 ops/sec ±0.29% (99 runs sampled)
+  Original  x 1,643,401 ops/sec ±0.08% (101 runs sampled)
+  Current   x 1,191,994 ops/sec ±0.13% (101 runs sampled)
 
 # Set #3
-  Original  x 946,995 ops/sec ±0.12% (101 runs sampled)
-  Current   x 37,336 ops/sec ±0.23% (96 runs sampled)
+  Original  x 947,281 ops/sec ±0.07% (101 runs sampled)
+  Current   x 924,929 ops/sec ±0.06% (98 runs sampled)
 ```
 
 ## Implementations in other languages

docs/api.error.md

@@ -2,166 +2,97 @@
 
 > [`@mcaskill/html-build-attributes/lib/error.js`](/src/lib/error.ts)
 
-The error module provides custom `Error` objects thrown to escape filters
-and when runtime errors occur.
+The error module provides a custom `Error` object meant to be used by
+filter functions. This is mostly useful to catch errors related to
+attribute value filtering.
 
 > For all API functions listed:
 >
-> * `AttrName` is a string and represents an attribute name.
-> * `AttrValue` is a string, boolean, or null, and represents a filtered attribute value.
 > * `T` represents any data type.
+> * `AttrName` is a string and represents an attribute name.
+> * `AttrValue` is a string or boolean and represents a filtered attribute value.
 
-## `FilterException()`
-
-The `FilterException` object represents an error with a value to be filtered.
+## `FilterError()`
 
-The [`BadValueException`](#badvalueerror) and [`TypeMismatchException`](#typemismatcherror)
-objects extend the `FilterException` object.
+The `FilterError` object represents an error with a value being filtered.
 
 ### Syntax
 
 ```ts
-new FilterException(message: string, options?: object)
+new FilterError(message: string, options?: object)
 ```
 
-## `FilterException.describeAttr()`
+## `FilterError.describeAttr()`
 
 A static method to format the attribute name or value.
 
-This method is used by the static creator methods to generate an error message.
+This method is used by the static creator method to generate a descriptor
+for the placeholder token.
 
 ### Syntax
 
 ```ts
-FilterException.describeAttr(value?: T, name?: AttrName): string
+FilterError.describeAttr(value?: T, name?: AttrName): string
 ```
 
 ### Examples
 
 ```js
-FilterException.describeAttr(null);
-// → null
-
-FilterException.describeAttr(undefined);
-// → undefined
-
-FilterException.describeAttr(true);
-// → boolean
-
-FilterException.describeAttr(42);
-// → number
+FilterError.describeAttr(null);
+// → 'null'
 
-FilterException.describeAttr('hello');
-// → string
+FilterError.describeAttr(undefined);
+// → 'undefined'
 
-FilterException.describeAttr([ 1, 2, 3 ]);
-// → array
+FilterError.describeAttr(true);
+// → 'boolean'
 
-FilterException.describeAttr(new Date());
-// → object
+FilterError.describeAttr(42);
+// → 'number'
 
-FilterException.describeAttr('hello', 'class');
-// → attribute [class]
-```
-
-## `FilterException.createNotFilterable()`
+FilterError.describeAttr([ 1, 2, 3 ]);
+// → 'Array'
 
-A static method to create a new error object with a generic "is not filterable"
-message derived from the provided parameters.
+FilterError.describeAttr({});
+// → 'Object'
 
-This method is recommended for creating `TypeMismatchException` objects.
+FilterError.describeAttr(new Date());
+// → 'Date'
 
-### Syntax
+FilterError.describeAttr('hello');
+// → 'string'
 
-```ts
-FilterException.createNotFilterable(
-  value?: T,
-  name?: AttrName,
-  options?: object
-): FilterException
+FilterError.describeAttr('hello', 'class');
+// → 'attribute [class]'
 ```
 
-### Example
-
-```js
-function filterNumber(value) {
-  if (typeof value === 'number') {
-    return value;
-  }
-
-  throw new TypeMismatchException.createNotFilterable(value);
-}
-```
-
-## `FilterException.createNotConcatenable()`
-
-A static method to create a new error object with a generic "is not concatenable"
-message derived from the provided parameters.
+## `FilterError.create()`
 
-This method is recommended for creating `TypeMismatchException` objects.
+A static method to create a new error object with a message where `{attr}`
+is a placeholder that will be substituded with a name or value.
 
 ### Syntax
 
 ```ts
-FilterException.createNotConcatenable(
-  value?: T,
+FilterError.create(
+  message: string,
+  value: T,
   name?: AttrName,
   options?: object
-): FilterException
+): FilterError
 ```
 
 ### Example
 
 ```js
-function filterList(value) {
-  const tokens = [];
-
-  for (const token of value) {
-    try {
-      tokens.push(filterString(token));
-    } catch (err) {
-      throw TypeMismatchException.createNotConcatenable(value, null, { cause: err });
-    }
-  }
-
-  return tokens;
-}
-```
-
-## `BadValueException()`
-
-The `BadValueException` object represents a value that
-a filter is unable to convert.
-
-### Example
-
-```js
-function assertFiniteNumber(value) {
-  if (Number.isFinite(value)) {
-    return value;
-  }
-
-  throw new BadValueException('number is not finite');
-}
-```
-
-## `TypeMismatchException()`
-
-The `TypeMismatchException` object represents a value that
-does not conform to the filter's constraints.
-
-For the [compose module](/docs/api.compose.md) and
-[aggregate filters](/docs/api.filter.md), this indicates a filter
-does not accept the value and should maybe try another filter.
-
-### Example
-
-```js
-function filterNumber(value) {
+function filterNumber(value, name) {
   if (typeof value === 'number') {
     return value;
   }
 
-  throw new TypeMismatchException('value is not a number');
+  throw FilterError.create('{attr} is not a number', value, name);
 }
+
+filterNumber(true);
+// → Uncaught FilterError: boolean is not a number
 ```