Options

The make function accepts an options object as its second argument:

Option	Type	Default	Description
strength	number	2	Number of factors to be covered (N-wise).
subModels	SubModelType[]	undefined	Apply a different combination strength to a specific group of factors.
weights	WeightsType	undefined	Index-keyed weights that bias value selection during row completion.
presets	PresetRowType[]	undefined	Rows that must be included in the output. Equivalent to PICT's seeding feature.
constraints	Expression[]	undefined	Declarative constraints evaluated under three-valued logic.
comparer	Comparer	undefined	Custom comparison functions for constraint evaluation.
sorter	Function	sorters.hash	Determines the order of combinations.
criterion	Function	criteria.greedy	Determines the algorithm for generating combinations.
salt	string | number	""	Value mixed into sorters.hash to control the ordering of pairs.
tolerance	number	0	Tolerance used by criteria.greedy to trade optimality for speed.

See also: PictModel for the PICT-compatible model parser, or Constraint Shortcuts for a concise constraint builder API.

---

strength

Number of factors to be covered. Default is 2 (pairwise).

caution

The more strength increases, the more the number of combinations increases exponentially. Use values greater than 2 only when truly needed.

Renamed from length

In versions prior to 3.0, this option was called length. The semantics are unchanged.

subModels

subModels lets you apply a different N-wise strength to a specific group of factors, while the rest of the factors stay at the default strength. This is the same concept as PICT's sub-models.

import { make } from "covertable";

const factors = {
  PLATFORM: ["Win", "Mac", "Linux"],
  CPUS:     ["1", "2", "4"],
  RAM:      ["512", "1024"],
  HDD:      ["SATA", "SSD"],
};

make(factors, {
  strength: 2,
  subModels: [
    { fields: ["PLATFORM", "CPUS", "RAM"], strength: 3 },
  ],
});

In this example:

• All combinations of PLATFORM, CPUS, and RAM are covered at strength 3.
• Pairs that span the sub-model and other factors (e.g. PLATFORM x HDD) are still covered at the default strength of 2.

weights

weights biases the completion phase — the moment CoverTable picks a value to fill in a column once all required pairs have been satisfied. Higher-weighted values are tried first, so they tend to appear in more rows.

import { make } from "covertable";

const factors = {
  OS:      ["Windows", "Linux", "Mac"],
  Browser: ["Chrome", "Firefox", "Safari"],
};

make(factors, {
  weights: {
    Browser: { 0: 10 }, // index 0 = "Chrome" gets weight 10 (default is 1)
  },
});

The keys of the inner object are indices into the factor's value array. To express weights by value instead, use the weightsByValue helper from covertable/pict.

How weights interact with coverage

Weights only affect the completion phase. The pairwise (or N-wise) coverage requirement is always satisfied first; weights only influence which values are picked when the algorithm has free choice. Setting a weight does not change the minimum number of generated rows.

presets

presets lets you specify rows that must appear in the output. CoverTable processes them before normal generation, so the pairs they cover are subtracted from the work that the generator has to do — often reducing the total number of generated rows.

import { make } from "covertable";

const factors = {
  OS:      ["iOS", "Android"],
  Browser: ["Safari", "Chrome", "Firefox"],
  Locale:  ["en", "ja", "fr"],
};

make(factors, {
  presets: [
    { OS: "iOS", Browser: "Safari", Locale: "en" },
    { OS: "Android", Browser: "Chrome" },
    { Browser: "Firefox" },
  ],
});

Behavior:

Case	Result
Full row, satisfies constraints	Output as-is, covered pairs are consumed
Partial row, can be completed within constraints	Completed via the normal fill-in logic, then output
Row violates constraints (or contains an unknown value)	Silently dropped
Row cannot be completed (e.g. constraints leave no valid filler)	Silently dropped

Equivalent to PICT's seeding (/e:file)

PICT calls this feature seeding and reads the seed rows from a tab-separated file via the /e:file.txt CLI option. CoverTable's presets is the same concept, expressed as plain JavaScript objects so you can compose them programmatically.

constraints

Declarative constraints evaluated under Kleene three-valued logic. See Constraint Logic for full documentation.

make(factors, {
  constraints: [
    // IF machine = iPhone THEN os = iOS
    { operator: 'or', conditions: [
      { operator: 'ne', left: 'machine', value: 'iPhone' },
      { operator: 'eq', left: 'os', value: 'iOS' },
    ]},
  ],
});

tip

Writing constraint objects by hand can be verbose. The Constraint shortcut class provides a concise builder API:

import { Constraint } from "covertable/shortcuts";
const c = new Constraint<typeof factors>();

make(factors, {
  constraints: [
    c.or(c.ne("$machine", "iPhone"), c.eq("$os", "iOS")),
  ],
});

sorter

Determines the order in which combinations are generated.

Sorter	Description
sorters.hash	Uses a hash-based method for reproducible results. Accepts a salt option. (default)
sorters.random	Generates different combinations each time. Fastest option.

import { make, sorters } from "covertable";

make(factors, { sorter: sorters.hash, salt: 42 });
make(factors, { sorter: sorters.random });

Salt for Reproducibility

When using sorters.hash, the salt option controls the ordering of unstored pairs. When the combination of factors and salt are the same, CoverTable reproduces the same result set. Changing the salt is the easiest way to explore alternative orderings without changing the input factors.

Renamed from seed

In versions prior to 3.0, this option was called seed. It was renamed to salt to avoid confusion with the PICT-style seeding feature (rows that must be included in the output).

criterion

Determines the efficiency of the covering algorithm.

Criterion	Description
criteria.greedy	Attempts to minimize the number of combinations, but is more time-intensive. (default)
criteria.simple	Quickly generates combinations, but may produce more rows.

import { make, criteria } from "covertable";

make(factors, { criterion: criteria.greedy });
make(factors, { criterion: criteria.simple });

Greedy Tolerance

The criteria.greedy criterion accepts a tolerance option to balance speed and result quality. Higher tolerance trades optimality for faster execution.