util-array-object-or-both2.7.67

Validate and normalise user choice: array, object or both?

§ Quick Take

import { strict as assert } from "assert";
import arrObjOrBoth from "util-array-object-or-both";

// normalises string, a user preference:

assert.equal(arrObjOrBoth("arrays"), "array");
assert.equal(arrObjOrBoth("array"), "array");
assert.equal(arrObjOrBoth("arr"), "array");
assert.equal(arrObjOrBoth("a"), "array");

assert.equal(arrObjOrBoth("objects"), "object");
assert.equal(arrObjOrBoth("object"), "object");
assert.equal(arrObjOrBoth("obj"), "object");
assert.equal(arrObjOrBoth("o"), "object");

assert.equal(arrObjOrBoth("whatever"), "any");
assert.equal(arrObjOrBoth("either"), "any");
assert.equal(arrObjOrBoth("both"), "any");
assert.equal(arrObjOrBoth("any"), "any");
assert.equal(arrObjOrBoth("all"), "any");
assert.equal(arrObjOrBoth("e"), "any");

§ Purpose

It standardises the input strings a user has given:


Assumed to be an array-typeobject-typeeither type
Input string:arrayobjectany

arraysobjectsall

arrobjeverything

arayobboth

arroeither

aeach

whatever

e

------------
Output string:arrayobjectany

§ API

arrObjOrBoth(str, [opts])

In other words, it's a function which takes two input arguments, second-one being optional (marked by square brackets).

If the input is valid, normalised version: array or object or any will be returned.

If the input is not valid, an error will be thrown.

Input argumentTypeObligatory?Description
inputStringyesLet users choose from variations of "array", "object" or "both". See above.
optsPlain objectnoOptional Options Object. See below for its API.

Options object lets you customise the thrown error message. It's format is the following:

`${opts.msg}The ${opts.optsVarName} was customised to an unrecognised value: ${str}. Please check it against the API documentation.`
options object's keyTypeObligatory?DefaultDescription
msgStringno``Append the message in front of the thrown error.
optsVarNameStringnogiven variableThe name of the variable we are checking here.

For example, set optsVarName to opts.only and set msg to ast-delete-key/deleteKey(): [THROW_ID_01] and the error message thrown if user misconfigures the setting will be, for example:

`ast-delete-key/deleteKey(): [THROW_ID_01] The variable "opts.only" was customised to an unrecognised value: sweetcarrots. Please check it against the API documentation.`

§ API - Output

Returns one of three possible string values: "array" or "object" or "any".

§ Use

// require this library:
const arrObjOrBoth = require('util-array-object-or-both')
// and friends:
const clone = require('lodash.clonedeep')
const checkTypes = require('check-types-mini')
const objectAssign = require('object-assign')
// let's say you have a function:
function myPrecious (input, opts) {
// now you want to check your options object, is it still valid after users have laid their sticky paws on it:
// define defaults:
let defaults = {
lalala: null,
only: 'object' // <<< this is the value we're particularly keen to validate, is it `array`|`object`|`any`
}
// clone the defaults to safeguard it, and then, object-assign onto defaults.
// basically you fill missing values with default-ones
opts = objectAssign(clone(defaults), opts)
// now, use "check-types-mini" to validate the types:
checkTypes(opts, defaults,
{
// give a meaningful message in case it throws,
// customise the library `check-types-mini`:
msg: 'my-library/myPrecious(): [THROW_ID_01]',
optsVarName: 'opts',
schema: {
lalala: ['null', 'string'],
only: ['null', 'string']
}
}
)
// by this point, we can guarantee that opts.only is either `null` or `string`.
// if it's a `string`, let's validate is its values among accepted-ones:
opts.only = arrObjOrBoth(opts.only, {
msg: 'my-library/myPrecious(): [THROW_ID_02]',
optsVarName: 'opts.only'
})
// now we can guarantee that it's either falsy (undefined or null) OR:
// - `object`
// - `array`
// - `any`

// now you can use `opts.only` in your function safely.
...
// rest of the function...
}

§ Use

We are going to use it in:

§ Licence

MIT opens in a new tab

Copyright © 2010–2020 Roy Revelt and other contributors

Related packages:

📦 util-nonempty 2.9.65
Is the input (plain object, array, string or whatever) not empty?