A validation and conditional assignment utility belt.
The most general util for validation is ensure
, wich uses JSON Schema to validate your data. However, be sure to take a look at the remaining utils
to find the best fits for your use cases.
import process from 'node:process';
import { collect, ensure } from 'ensurism';
// Will always be 'development', 'production', or 'test'
const NODE_ENV = ensure(process.env.NODE_ENV, {
type: 'string',
enum: ['development', 'production', 'test'],
default: 'development'
});
// Collecting -mapping- properties
const env = collect(process.env, ({ get, assert, ensure, coerce }) => ({
FOO_VAR: get(),
BAR_VAR: assert(),
APP_URI: ensure({ type: 'string', format: 'uri' }),
APP_PORT: coerce('number'),
NODE_ENV: ensure({
type: 'string',
enum: ['development', 'production', 'test'],
default: 'development'
})
}));
You might want to create a configuration object that relies on certain values. In the example below, we collect
environment variables, and later use select
to conditionally set the properties bar
and baz
for our final configuration object.
import process from 'node:process';
import { into } from 'pipettes';
import { collect, select } from 'ensurism';
export const configuration = into(
collect(process.env, ({ ensure }) => ({
NODE_ENV: ensure({
type: 'string',
enum: ['development', 'production', 'test'],
default: 'development'
})
})),
({ NODE_ENV }) => ({
env: NODE_ENV,
foo: 'foo',
bar: select(NODE_ENV, {
default: 1,
production: 2,
development: 3
}),
baz: select(NODE_ENV, {
default: 1,
production: 2,
test: 4
})
})
);
Throws if data
is undefined
.
- Signature:
assert(data, options)
- Params:
data
: the input data.options
: optional object with optional properties:name
: a name to be used for error messages.message
: an error message to use instead of the default.deep
: iftrue
anddata
is an array or a record,assert
will also throw if any of their elements areundefined
.
- Returns: the input
data
.
import { assert } from 'ensurism';
// Succeed
assert('foo');
assert([undefined]);
// Fail
assert(undefined);
assert([undefined], { deep: true });
Returns the input data
for records and basic types; for arrays, however, one of multiple strategies can be applied:
- Signature:
take(data, options)
- Params:
data
: the input data.options
: optional object with optional properties:name
: a name to be used for error messages.assert
: whether to assert the final output value is notundefined
.strategy
: applies todata
arrays; one of:"first"
: it will return the first array item, if any. This is the default strategy."one"
: it will throw if the input array has more than one element, and return its first item, if any."maybe"
: it will return the first defined array item, if any.
- Returns: the input
data
if it is a record or a basic type; ifdata
is an array, it will return adata
array value as per the specifiedstrategy
.
import { take } from 'ensurism';
// Succeed
take(['foo'], { strategy: 'one' }); // 'foo'
take(['foo', 'bar'], { strategy: 'first' }); // 'foo'
take([undefined, 'foo'], { strategy: 'maybe' }); // 'foo'
// Fail
take(['foo', 'bar'], { strategy: 'one' });
take([undefined], { assert: true, strategy: 'first' });
Throws if data
doesn't conform to a given schema
. If the schema
has default
values, they will be assigned to the returned data. Additional properties, when allowed by the schemas, will not be removed. No mutation will occurr for input data.
Uses JSON Schema validation, as implemented by ajv. Further string format validation is provided by ajv-formats and ajv-formats-draft2019.
- Signature:
ensure(data, schema, options)
- Params:
data
: the input data.schema
: either a JSON Schema object with atype
property, or a valid schema type, as a string.options
: optional object with optional properties:name
: a name to be used for error messages; if empty,schema.title
will be used instead when available.assert
: whether to assert the final output value is notundefined
.
- Returns: a clone of the input
data
with, if it applies, the default values assigned as specified byschema
.
import { ensure } from 'ensurism';
// Succeed
ensure('foo', 'string'); // 'foo'
ensure(undefined, 'string'); // undefined
ensure(undefined, { type: 'string', default: 'foo' }, { assert: true }); // 'foo'
// Fail
ensure('foo', 'number');
ensure(undefined, 'string', { assert: true });
Coerces data
to the root schema
type, then validates the data against the schema
by using ensure
. Inner elements for objects and arrays will not be coerced.
- Signature:
coerce(data, schema, options)
- Params:
data
: the input data;undefined
won't be coerced into the schema type.schema
: either a JSON Schema object with atype
property, or a valid schema type, as a string.options
: optional object with optional properties:name
: a name to be used for error messages; if empty,schema.title
will be used instead when available.assert
: whether to assert the final output value is notundefined
.
- Returns: a clone of the input
data
with, if it applies, the default values assigned as specified byschema
.
The coercion rules from each data
input type are as follows:
- strings:
"string"
: returns the input string with quotes ("
) removed, if within quotes."number"
,"integer"
: fails ifNaN
."boolean"
:false
for falsy value strings:""
"\"\""
"0"
"false"
"null"
"undefined"
"NaN"
"null"
: fails if not a falsy value string."array"
,"object"
: parses withJSON.parse
; fails if not a JSON string.
- numbers:
"string"
: a number string."number"
,"integer"
: a number."boolean"
:false
for0
,true
otherwise."null"
: fails if not0
."array"
,"object"
: it will fail.
- boolean:
"string"
:"true"
or"false"
."number"
,"integer"
:0
forfalse
;1
fortrue
."boolean"
: same as data source."null"
: fails if notfalse
."array"
,"object"
: it will fail.
- null:
"string"
:"null"
."number"
,"integer"
:0
."boolean"
:false
."null"
:null
."array"
,"object"
: it will fail.
- array:
"string"
,"number"
,"integer"
,"boolean"
,"null"
: it will fail."array"
: same as data source."object"
: an object with index numbers as keys.
- object:
"string"
,"number"
,"integer"
,"boolean"
,"null"
: it will fail."array"
: an array of object values."object"
: same as data source.
import { coerce } from 'ensurism';
// These will succeed
coerce('foo', 'string'); // 'foo'
coerce('"foo"', 'string'); // 'foo'
coerce('0', 'number'); // 0
coerce('foo', 'boolean'); // true
coerce('null', 'boolean'); // false
coerce('false', 'null'); // null
coerce('{ "foo": "bar" }', 'object'); // { foo: 'bar' }
coerce(10, 'boolean'); // true
coerce(0, 'null'); // null
// These will fail
coerce('foo', 'number');
coerce('foo', 'null');
coerce('1, 2, 3', 'array');
coerce(1, 'null');
Given a value and a selector
object, it will return the value of the selector
's property matching that value. If selector
doesn't have such property but it does have a default
key, it will return its value instead.
If a strategy
other than "fallback"
is specified, the selected value -if any- will be merged with the default
value -if any- following the specified strategy.
- Signature:
select(data, selector, options)
- Params:
data
: property to select fromselector
.selector
: and object of values.options
: optional object with optional properties:name
: a name to be used for error messages.assert
: whether to assert the final output value is notundefined
.strategy
: applied when there's both aselector.default
and data forvalue
-see merge strategies; one of:"fallback"
: returns the data forselector[value]
if available, otherwise returnsselector.default
. This is the default strategy."shallow"
: produces a shallow merge clone of the data."merge"
: produces a deep merge clone of the data, excluding arrays."deep"
: produces a deep merge clone of the data, including arrays.
import { select } from 'ensurism';
// These will succeed
select('foo', { foo: 'bar', bar: 'baz' }); // 'bar'
select('foo', { default: 'bar', bar: 'baz' }); // 'bar'
select('foo', { default: { bar: 'bar' }, foo: { baz: 'baz' } }, { strategy: 'shallow' }); // { bar: 'bar', baz: 'baz' }
// These will fail
select('foo', { bar: 'baz' }, { assert: true });
A conveniency function for when you want to use any of the previous utils for several keys in an object, and expect the response to contain similarly named properties.
- Signature:
collect(data, collection, options)
- Params:
data
: an object of values.collector
: a function, taking an object with methodsget
,assert
,take
,ensure
,coerce
, andselect
as an argument. These methods have the same signature as the similarly named functions but omitting their firstdata
argument.options
: optional object with optional properties:failEarly
: boolean, whether to fail as soon as one of the values throw, otherwise compacting all errors in a single error. Default:false
.
- Returns: an object as defined by
collector
.
import { collect } from 'ensurism';
const result = collect(
{
a: 'foo',
b: 'bar',
c: ['baz', 'foobar'],
d: 'foobaz',
e: 'barfoo',
f: 'barbaz'
},
({ get, assert, take, ensure, coerce, select }) => ({
a: get(),
b: assert(),
c: take('first'),
d: ensure('string'),
e: coerce('boolean'),
f: select({
default: true,
barbaz: false
})
})
);
// `result` would be an object such as:
({
a: 'foo',
b: 'bar',
c: 'baz',
d: 'foobaz',
e: true,
f: false
});