util-array-object-or-both^2.8.0

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

Install via npm

npm i util-array-object-or-both

The default is exported, so instead of arrObjOrBoth below, you can name the consumed function however you want.

Consume via a require():

const arrObjOrBoth = require("util-array-object-or-both");

or as an ES Module:

import arrObjOrBoth from "util-array-object-or-both";

Install as a script, via CDN

Put this in your HTML:

<script src="https://cdn.jsdelivr.net/npm/util-array-object-or-both/dist/util-array-object-or-both.umd.js">

Then, you’ll get a global variable utilArrayObjectOrBoth in your Global object and you consume it like this:

const arrObjOrBoth = utilArrayObjectOrBoth;

This arrObjOrBoth is your main function. See its API in the main section.

Trivia

This program has 34 assertions in its unit tests. That's less than all unit test assertions' median (50) and less than geometric mean (70).

In monorepo, 2 other packages consume this package.

§ 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");

⬆ back to top

§ 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`

⬆ back to top

§ 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.`

⬆ back to top

§ 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...
}