util-array-object-or-both4.0.1

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-type object-type either type
Input string: array object any

arrays objects all

arr obj everything

aray ob both

arr o either

a each

whatever

e

---- ---- ----
Output string: array object any

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 argument Type Obligatory? Description
input String yes Let users choose from variations of "array", "object" or "both". See above.
opts Plain object no Optional 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 key Type Obligatory? Default Description
msg String no `` Append the message in front of the thrown error.
optsVarName String no given variable The 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:

Changelog

See it in the monorepo opens in a new tab, on GitHub.

Contributing

To report bugs or request features or assistance, raise an issue on GitHub opens in a new tab.

Any code contributions welcome! All Pull Requests will be dealt promptly.

Licence

MIT opens in a new tab

Copyright © 2010–2021 Roy Revelt and other contributors

Related packages:

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