Installation
Quick Take
2022 Update
This is one of our early, pre-TypeScript libraries. Today, I’d just offer one of three values to pick and call it a day. There’s very little practical benefit from giving user a variety of values to pick from. User will have to look at documentation anyway. Not to mention, TypeScript Intellisense will suggest the values.
Purpose
It standardises the input strings a user has given:
Turned into "array" | Turned into "object" | Turned into "any" |
|---|---|---|
array | ||
array | object | any |
arrays | ||
arrays | objects | all |
arr | ||
arr | obj | everything |
aray | ||
aray | ob | both |
arr | ||
arr | o | either |
a | ||
a | each | |
whatever | ||
whatever | ||
e | ||
e | ||
API — arrObjOrBoth()
The main function arrObjOrBoth() is imported like this:
It’s a function which takes two input arguments:
| Input argument | Type | Obligatory | Description |
|---|---|---|---|
inputType: String Obligatory: yes | |||
input | String | yes | Let users choose from variations of “array”, “object” or “both”. See above. |
optsType: Plain object Obligatory: no | |||
opts | Plain object | no | Optional Options Object. See below for its API. |
Options object lets you customise the thrown error message:
| Key | Type | Obligatory | Default | Description |
|---|---|---|---|---|
msgType: String Obligatory: no Default: Empty string | ||||
msg | String | no | Empty string | Append the message in front of the thrown error. |
optsVarNameType: String Obligatory: no Default: given variable | ||||
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.`;
Here are all defaults in one place for copying:
Function will return one of three possible string values: "array" or "object" or "any".
API — defaults
You can import defaults:
It's a plain object:
The main function calculates the options to be used by merging the options you passed with these defaults.
API — version
You can import version:
Use
// require this library:
import { arrObjOrBoth } from 'util-array-object-or-both';
// and friends:
import clone from 'lodash.clonedeep'
import {checkTypes} from 'check-types-mini'
// let's say you have a function:
function myFunc (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
const resolvedOpts = {...defaults, ...opts};
// now, use "check-types-mini" to validate the types:
checkTypes(resolvedOpts, 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:
resolvedOpts.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...
}