The filter modules are a collection of functions and function factories to approve, reject, and mutate a value.
For all API functions listed:
Trepresents any data type.AttrNameis a string and represents an attribute name.AttrValueis a string or boolean and represents a filtered attribute value.AttrValueFilteris a function signature representing the filter.
This type represents the signature of a filter function.
(value: T, name?: AttrName, fallback?: AttrValueFilter | AttrValue) => AttrValuefunction filterNumber(value, name, fallback = false) {
if (typeof value === 'number') {
return value;
}
return fallback;
}For a custom filter to play nice as middleware,
it is recommended to use the filterFallback() function
to resolve any fallbacks that might be a function:
import {
filterFallback,
} from '@mcaskill/html-build-attributes/value/filter-fallback.js';
function filterNumber(value, name, fallback = false) {
if (typeof value === 'number') {
return value;
}
return filterFallback(value, name, fallback);
}Creates a filter function that applies the given filter to a given value or it's returned result if the value is a function.
createFilterCallable(
filter: AttrValueFilter
): AttrValueFilterimport {
createFilterCallable
} from '@mcaskill/html-build-attributes/value/filter-function.js';
const filterNumber = (value, name, fallback = false) => {
if (typeof value === 'number') {
return value;
}
return fallback;
};
const filterValueOrClosure = createFilterCallable(
filterNumber
);
filterValueOrClosure(42);
// → 42
filterValueOrClosure(() => (42 * 2));
// → 84
filterValueOrClosure('hello');
// → false
filterValueOrClosure(() => 'hello');
// → falseCreates a filter function that applies a filter to each item of the array and concatenates the list into a string separated by a customizable delimiter.
createFilterList(
filter: AttrValueFilter,
oneOrManySeparators: string | object<AttrName, string>,
fallbackSeparator?: string
): AttrValueFilterimport {
createFilterList
} from '@mcaskill/html-build-attributes/value/filter-list.js';
const filterTokenList = createFilterList(filterToken, {
'coords': ',',
}, ':');
filterTokenList([ 'a', 'b', 'c' ]);
// → a:b:c
filterTokenList([ 'a', 'b', 'c' ], 'coords');
// → a,b,c
const scopedFilterTokenList = createFilterList(filterToken, {
'class': ' ',
});
scopedFilterTokenList([ 'a', 'b', 'c' ], 'class');
// → a b c
scopedFilterTokenList([ 'a', 'b', 'c' ]);
// → TypeError<array separator is not defined>
scopedFilterTokenList([ 'a', 'b', 'c' ], 'rel');
// → TypeError<attribute [rel] separator is not defined>Creates a filter function from a collection of filters that returns the filtered value from the first filter that returns a value.
createFilterMiddleware(
filters: AttrValueFilter[]
): AttrValueFilterimport {
createFilterMiddleware
} from '@mcaskill/html-build-attributes/value/filter-middleware.js';
const filterString = (value, name, next) => {
if (typeof value === 'string') {
return value;
}
return next(value, name);
};
const filterNumber = (value, name, next) => {
if (typeof value === 'number') {
return value;
}
return next(value, name);
};
const filterByType = createFilterMiddleware([
filterString,
filterNumber,
]);
filterByType('hello');
// → 'hello'
filterByType(42);
// → 42
filterByType([]);
// → false
filterByType(true);
// → false
filterByType(true, 'test', 'fallback');
// → 'fallback'This function resolves the fallback of an attribute value filter.
If the fallback argument is a function it is assumed to be another filter and is called with the value and name arguments, otherwise it is assumed to be the value to return.
filterFallback(
value: T,
name?: AttrName,
fallback?: AttrValueFilter | AttrValue
): AttrValueimport {
filterFallback
} from '@mcaskill/html-build-attributes/value/filter-fallback.js';
function filterNumber(value, name, fallback = false) {
if (typeof value === 'number') {
return value;
}
return filterFallback(value, name, fallback);
}
filterNumber('hello', 'value');
// → false
filterNumber('hello', 'value', 0);
// → 0
filterNumber('hello', 'value', (value, name) => Number.parseInt(value));
// → NaNThis function converts a value to a string representation or to a JSON string.
filterStringable(value: T, name?: AttrName): AttrValueIf the value is not nullish (null or undefined) and:
-
a
Date, the attribute is rendered and the value is converted to ISO format. -
stringable, the attribute is rendered and the value is converted to its string representation.
-
Otherwise, the attribute is rendered and the value is serialized as a JSON string.
import {
filterStringable
} from '@mcaskill/html-build-attributes/value/filter-stringable.js';
filterStringable(new Date(2006, 0, 2, 15, 4, 5));
// → 2006-01-02T20:04:05.000Z
class Person {
constructor(id, name) {
this.id = id;
this.name = name;
}
}
filterStringable(new Person(1, 'Tim'));
// → {"id":1,"name":"Tim"}
class JsonablePerson extends Person {
toJSON() {
return `${this.id}:${this.name}`;
}
}
filterStringable(new JsonablePerson(1, 'Tim'));
// → "1:Tim"
class StringablePerson extends Person {
toString() {
return this.name;
}
}
filterStringable(new StringablePerson(1, 'Tim'));
// → TimThis function filters a value that is a string, number, boolean, or BigInt.
This filter is designed to replicate the behaviour of most token list
attributes such as accept, class, coords, rel, sizes, and srcset.
filterToken(value: T, name?: AttrName): AttrValueIf the value is:
-
a string, the value is concatenated.
Leading and trailing whitespace is preserved.
An empty string is rendered.
-
a boolean, the value is converted to a string and is concatenated.
-
a BigInt, the value is concatenated.
-
a number and finite, the value is concatenated.
A sign of
-0is preserved.
This function filters a value that is a string, number, boolean, or BigInt.
This filter is designed to replicate the behaviour of most attributes including boolean attributes and WAI-ARIA attributes.
filterValue(value: T, name?: AttrName): AttrValueIf the value is:
-
a boolean and
-
the attribute name starts with
aria-, the boolean is converted to a string. -
is
true, only the attribute name is rendered. -
is
false, the attribute is discarded.
-
-
a string, the attribute is rendered.
Leading and trailing whitespace is preserved.
An empty string is rendered.
-
a BigInt, the attribute is rendered.
-
a number and finite, the attribute is rendered.
A sign of
-0is preserved.