Package Exports

object-all-values-equal-to

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (object-all-values-equal-to) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

object-all-values-equal-to

Does the AST/nested-plain-object/array/whatever contain only one kind of value?

Install
Purpose
API
Why we need this
Contributing
Licence

Install

npm i object-all-values-equal-to

// consume as a CommonJS require:
const allValuesEqualTo = require("object-all-values-equal-to");
// or as an ES Module:
import allValuesEqualTo from "object-all-values-equal-to";

Here's what you'll get:

Type	Key in `package.json`	Path	Size
Main export - CommonJS version, transpiled to ES5, contains `require` and `module.exports`	`main`	`dist/object-all-values-equal-to.cjs.js`	2 KB
ES module build that Webpack/Rollup understands. Untranspiled ES6 code with `import`/`export`.	`module`	`dist/object-all-values-equal-to.esm.js`	2 KB
UMD build for browsers, transpiled, minified, containing `iife`'s and has all dependencies baked-in	`browser`	`dist/object-all-values-equal-to.umd.js`	37 KB

⬆ back to top

Purpose

It answers the question: does the given AST/nested-plain-object/array/whatever contain only one kind of value?

The equality is not explicit, that is, we're just checking, that all values are not unequal to the given-one.

For example:

const allValuesEqualTo = require("object-all-values-equal-to");

// are all values equal to "false":
console.log(allValuesEqualTo({ a: false, c: false }, false));
// => true

// are all values equal to "false":
console.log(allValuesEqualTo({ a: false, c: "zzz" }, false));
// => false, because of `zzz`

// are all values equal to "false":
console.log(
  allValuesEqualTo(
    {
      a: {
        b: false,
        c: [
          {
            d: false,
            e: false
          },
          {
            g: false
          }
        ]
      },
      c: false
    },
    false
  )
);
// => true

⬆ back to top

`opts.arraysMustNotContainPlaceholders`

When working with data structures, this library would be used to check, is the certain piece of JSON data (some key's value, a nested object) is all blank, that is, contains only placeholders everywhere.

Now, with regards to arrays, default arrays should not contain placeholders directly. For example key b is customised, it's not a placeholder:

{
  "a": false,
  "b": [false]
}

It should be instead:

{
  "a": false,
  "b": []
}

When checking against second argument false, this library will yield false for former and true for latter.

Now, this is relevant only when working with data structures. When dealing with all other kinds of nested objects and arrays, placeholders within arrays count as placeholders and should yield true.

For that, turn off the opts.arraysMustNotContainPlaceholders, set it to false.

Observe:

let res1 = allValuesEqualTo([null], null);
console.log(res1);
// => false

let res2 = allValuesEqualTo([null], null, {
  arraysMustNotContainPlaceholders: false
});
console.log(res2);
// => true

⬆ back to top

API

allValuesEqualTo(input, value);

API - Input

Input argument	Type	Obligatory?	Default	Description
`input`	Whatever	yes	`undefined`	AST tree, or object or array or whatever. Can be deeply-nested. Hopefully contains some nested plain objects. We love nested plain objects.
`value`	Whatever	no	`false`	We will check, does `input` contain only `value` on every key. Please don't set it to `undefined`.

⬆ back to top

Optional Options Object

options object's key	Type of its value	Default	Description
{
`arraysMustNotContainPlaceholders`	Boolean	`true`	When set to `true`, `value` within array should not be present and will yield `false` result. Set this to `false` to allow one or more `value`'s within arrays in the `input`.
}

The Optional Options Object is validated by check-types-mini, so please behave: the settings' values have to match the API and settings object should not have any extra keys, not defined in the API. Naughtiness will cause error throws. I know, it's strict, but it prevents any API misconfigurations and helps to identify some errors early-on.

Here are the Optional Options Object's defaults in one place (in case you ever want to copy and tweak it):

{
  arraysMustNotContainPlaceholders: true,
}

⬆ back to top

API - Output

Boolean: true or false.

Why we need this

For example, I was working on object-fill-missing-keys. The library takes an object, a reference object, and fills in missing keys according to the reference. I was implementing a feature, a options switch, which let to skip filling for chosen keys if they currently contain only placeholders.

You'll need this library when you want to check, does the AST contain only certain value throughout the whole tree. Also, it can be a simple object, in which case, we'd be checking, are all values of all keys equal to something.

⬆ back to top

Contributing

If you want a new feature in this package or you would like us to change some of its functionality, raise an issue on this repo.
If you tried to use this library but it misbehaves, or you need advice setting it up, and its readme doesn't make sense, just document it and raise an issue on this repo.
If you would like to add or change some features, just fork it, hack away, and file a pull request. We'll do our best to merge it quickly. Prettier is enabled, so you don't need to worry about the code style.

⬆ back to top

Licence

MIT License (MIT)