object-boolean-combinations

Generate an array full of object copies, each containing a unique Boolean value combination. Includes overrides.

Table of Contents

• Install
• What it does
• API
• Overriding
• Overriding the combinations — in practice
• Contributing
• Licence

Install

npm i object-boolean-combinations

// consume as a CommonJS require:
const objectBooleanCombinations = require("object-boolean-combinations");
// or as an ES Module:
import objectBooleanCombinations from "object-boolean-combinations";

Here's what you'll get:

⬆ back to top

What it does

It consumes a plain object, takes its keys (values don't matter) and produces an array with every possible combination of each key's Boolean^ value. If you have n keys, you'll get 2^n objects in the resulting array.

const objectBooleanCombinations = require("object-boolean-combinations");
const test = objectBooleanCombinations({ a: "whatever" });
console.log(`test = ${JSON.stringify(test, null, 4)}`);
// => [
//      {a: 0},
//      {a: 1}
//    ]

^ We could generate true/false values, but for efficiency, we're generating 0/1 instead. Works the same in Boolean logic, but takes up less space.

PS. Observe how input values don't matter, we had: { a: 'whatever' }.

Sometimes, you don't want all the combinations, you might want to "pin" certain values to be constant across all combinations. In those cases, use overrides, see below.

⬆ back to top

API

objectBooleanCombinations(inputObject, [overrideObject]);

API - Input

⬆ back to top

Overriding

Sometimes you want to override the object keys, for example, in the a settings object, I want to override all a and b keys to be only true (1). This reduces the object combinations from 2^3 = 8 to: 2^(3-2) = 2^1 = 2:

const objectBooleanCombinations = require("object-boolean-combinations");
const test = objectBooleanCombinations(
  { a: 0, b: 0, c: 0 },
  { a: 1, b: 1 } // <----- Override. These values will be on all combinations.
);
console.log(`test = ${JSON.stringify(test, null, 4)}`);
// => [
//      {a: 1, b: 1, c: 0},
//      {a: 1, b: 1, c: 1}
//    ]

In example above, a and b are "pinned" to 1, thus reducing the amount of combinations by power of two, essentially halving resulting objects count twice. Notice how only c is having variations.

⬆ back to top

Overriding the combinations — in practice

In practice, I use this overriding to perform the specific tests on Detergent.js. For example, let's say, I am testing: does Detergent encode entities correctly. In that case I need two arrays filled with objects:

• first array — encodeEntities = true and all possible combinations of the other 9 settings (2^(10-1)=512 objects in array)
• second array — encodeEntities = false and all possible combinations of the rest — again 512 objects in array.

Here's an AVA test, which uses objectBooleanCombinations() to create a combinations array of settings objects, then uses forEach() to iterate through them all, testing each:

test("encode entities - pound sign", t => {
  objectBooleanCombinations(sampleObj, {
    convertEntities: true
  }).forEach(function(elem) {
    t.is(
      detergent("\u00A3", elem),
      "£",
      "pound char converted into entity"
    );
  });
});

⬆ back to top

Contributing

• If you see an error, raise an issue.
• If you want a new feature but can't code it up yourself, also raise an issue. Let's discuss it.
• If you tried to use this package, but something didn't work out, also raise an issue. We'll try to help.
• If you want to contribute some code, fork the monorepo via BitBucket, then write code, then file a pull request via BitBucket. We'll merge it in and release.

In monorepo, npm libraries are located in packages/ folder. Inside, the source code is located either in src/ folder (normal npm library) or in the root, cli.js (if it's a command line application).

The npm script "dev", the "dev": "rollup -c --dev --silent" builds the development version retaining all console.logs with row numbers. It's handy to have js-row-num-cli installed globally so you can automatically update the row numbers on all console.logs.

⬆ back to top

Licence

MIT License

Copyright (c) 2015-2019 Roy Revelt and other contributors