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 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)

Copyright © 2018 Codsen Ltd, Roy Revelt