update README and types

Author: righ

typescript/README.md

@@ -2,6 +2,9 @@
 [![Workflow](https://github.com/walkframe/covertable/actions/workflows/typescript.yaml/badge.svg)](https://github.com/walkframe/covertable/actions/workflows/typescript.yaml)
 [![codecov](https://codecov.io/gh/walkframe/covertable/branch/master/graph/badge.svg)](https://codecov.io/gh/walkframe/covertable)
 
+# What is covertable?
+covertable is a powerful tool for generating pairwise combinations of input factors, designed for both Node.js and browser environments. It's easy to use, flexible, and supports advanced filtering options, making it perfect for testing scenarios and generating comprehensive datasets.
+
 # Installation
 
 ```sh
@@ -10,107 +13,101 @@ $ npm install covertable --save
 
 # Usage
 
-## Simple demo in Node.js:
+## Simple usage in Node.js:
 
 ```javascript
 var covertable = require('covertable');
-var make = covertable.default;
+var make = covertable.make;
 
-var machine = ['iphone', 'pixel'];
-var os = ['ios', 'android'];
-var browser = ['FireFox', 'Chrome', 'Safari'];
+var machine = ["iPhone", "Pixel", "XPERIA", "ZenFone", "Galaxy"];
+var os = ["iOS", "Android"];
+var browser = ["FireFox", "Chrome", "Safari"];
 
 make([machine, os, browser]);
 ```
 Output:
 
 ```javascript
 [
-  [ 'pixel', 'android', 'Chrome' ],
-  [ 'pixel', 'ios', 'Safari' ],
-  [ 'pixel', 'android', 'FireFox' ],
-  [ 'iphone', 'android', 'Safari' ],
-  [ 'iphone', 'ios', 'Chrome' ],
-  [ 'iphone', 'ios', 'FireFox' ]
+  [ 'Pixel', 'iOS', 'Chrome' ],
+  [ 'ZenFone', 'iOS', 'FireFox' ],
+  [ 'Pixel', 'Android', 'Safari' ],
+  [ 'Galaxy', 'Android', 'Chrome' ],
+  [ 'XPERIA', 'Android', 'FireFox' ],
+  [ 'Pixel', 'iOS', 'FireFox' ],
+  [ 'iPhone', 'iOS', 'Safari' ],
+  [ 'Galaxy', 'iOS', 'Safari' ],
+  [ 'XPERIA', 'iOS', 'Chrome' ],
+  [ 'ZenFone', 'Android', 'Chrome' ],
+  [ 'Galaxy', 'iOS', 'FireFox' ],
+  [ 'iPhone', 'Android', 'Chrome' ],
+  [ 'iPhone', 'iOS', 'FireFox' ],
+  [ 'ZenFone', 'iOS', 'Safari' ],
+  [ 'XPERIA', 'iOS', 'Safari' ]
 ]
 ```
 
 Of course, it also works in the browser well.
 
-## Advanced demo in TypeScript:
+## Advanced usage in TypeScript:
 
-```typescript
-import { default as make, makeAsync, sorters, criteria } from "covertable";
-
-const machine = ['iphone', 'pixel'];
-const os = ['ios', 'android'];
-const browser = ['FireFox', 'Chrome', 'Safari'];
-
-make([machine, os, browser], { // optional
-  length: 2, // default: 2
-  criterion: criteria.simple, // default: criteria.greedy
-  sorter: sorters.random, // default: sorters.hash
-  preFilter: (row: any) => !(row[1] === 'android' && row[0] !== 'pixel'), // default: null
-  postFilter: (row: any) => !(row[1] === 'ios' && row[2] !== 'Safari'), // default: null
-});
-```
+As previously mentioned, when elements are specified as an array, the results will also be in array form. However, if the elements are specified as an object, the results will be in object form. 
 
-Output:
+The following example uses preFilter and postFilter to apply constraints to the output results. In this case, `SuggestRowType` can also be used to infer the type of row parameters that the filter function receives.
 
 ```typescript
-[ // filtered
-  [ 'iphone', 'ios', 'Safari' ],
-  [ 'pixel', 'android', 'Chrome' ],
-  [ 'pixel', 'ios', 'Safari' ]
-]
-```
+import { make, sorters, criteria, SuggestRowType, DictType } from "covertable";
 
-You can use also `makeAsync` function (generator).
-- It receives the same arguments with `make` function.
-- It returns the row at the time it's made.
+const machine = ["iPhone", "Pixel", "XPERIA", "ZenFone", "Galaxy"];
+const os = ["iOS", "Android"];
+const browser = ["FireFox", "Chrome", "Safari"];
 
-## Object input and output
+const factors = {machine, os, browser};
 
-You can specify `factors` as object type:
-
-```typescript
-import { default as make, sorters, criteria } from "covertable";
-
-const machine = ['iphone', 'pixel'];
-const os = ['ios', 'android'];
-const browser = ['FireFox', 'Chrome', 'Safari'];
-
-make({machine, os, browser}, { // optional
+make(factors, { // optional
   length: 2,
-  preFilter: (row: any) => !(row.os === 'android' && row.machine !== 'pixel'), // default: null
-  postFilter: (row: any) => !(row.os === 'ios' && row.browser !== 'Safari'), // default: null
+  // SuggestRowType<typeof factors> is { machine: string, os: string, browser: string }
+  preFilter: (row: SuggestRowType<typeof factors>) => !(row.os === 'Android' && row.machine !== 'Pixel'), // default: null
+  // Or DictType that is { [key: string]: string }
+  postFilter: (row: DictType) => !(row.os === 'iOS' && row.browser !== 'Safari'), // default: null
 });
 ```
 
 Then the output will change as follows:
 
 ```typescript
 [ // filtered
-  { machine: 'iphone', browser: 'Safari', os: 'ios' },
-  { machine: 'pixel', browser: 'Chrome', os: 'android' },
-  { machine: 'pixel', browser: 'Safari', os: 'ios' },
+  { machine: 'Pixel', os: 'Android', browser: 'FireFox' },
+  { machine: 'iPhone', os: 'iOS', browser: 'Safari' },
+  { machine: 'Galaxy', browser: 'Safari', os: 'iOS' },
+  { machine: 'Pixel', browser: 'Safari', os: 'iOS' },
+  { machine: 'ZenFone', browser: 'Safari', os: 'iOS' },
+  { machine: 'XPERIA', browser: 'Safari', os: 'iOS' }
 ]
 ```
 
-## Options
-`covertable.make` function has options as `object` at 2nd argument.
+You can use also `makeAsync` function (generator).
+- It receives the same arguments with `make` function.
+- It returns the row at the time it's made.
 
-All options are omittable.
+```js
+import { makeAsync } from "covertable";
+
+for await (const row of makeAsync([machine, os, browser])) {
+  console.log(row);
+}
+```
+
+## Options
+The `covertable.make` function accepts an options object as its second argument. Here are the available options:
 
 ### length
 Number of factors to be covered. (default: 2)
 
 Obviously the more it increases, the more number of combinations increases.
 
 ### sorter
-Combinations depend on the order of spreading all over the rows.
-
-You can choice a sorter from the following:
+Determines the order of combinations.
 
 - sorters.random: It makes different combinations everytime. (fastest)
 - sorters.hash: It makes combinations depending on hash of the pair and seed. (default)
@@ -120,7 +117,7 @@ You can choice a sorter from the following:
     - When the combination of factors and seed are the same, covertable reproduces the same collective.
 
 ### criterion
-You can choice a criterion from the following:
+Determines the efficiency of combinations.
 
 - `criteria.simple`: it extracts any pairs that can be stored into the processing row.
 - `criteria.greedy`: it attempts to make most efficient combinations. (default)
@@ -132,23 +129,69 @@ Although the latter is superior to former in terms of fewer combinations general
 Not relevant options will be ignored.
 
 ### preFilter
-This is a function to filter beforehand.
-
-It receives an argument `row` as `object` type.
+Function to filter combinations before they are registered.
 
 When the function returns `false`, the row combination will not be registered.
 - If factors type is `Array`, you should specify an index at the subscript like `row => row[1] < 6`.
 - If factors type is `Object`, you should specify a key at the subscript like `row => row.month < 6` or `row => row['month'] < 6`
 
 ### postFilter
-This means a function to filter later.
+Function to filter combinations after they are generated.
 
 The usage is the same as `preFilter`, only the difference is the timing of the call.
 It will delete rows not matched this function at the last.
 
 For this reason, the final test cases may not satisfy the factors coverage.
 
-# Requirement
+### PictConstraintsLexer
+
+Filter functions can also be generated using PictConstraintsLexer. Use as follows
+This function is supported only in the typescript version.
+
+```js
+import { make, PictConstraintsLexer } from "covertable";
+
+const machine = ["iPhone", "Pixel", "XPERIA", "ZenFone", "Galaxy"];
+const os = ["iOS", "Android"];
+const browser = ["FireFox", "Chrome", "Safari"];
+
+const lexer = new PictConstraintsLexer(
+  `
+  IF [machine] = "iPhone" THEN [os] = "iOS";
+  IF [os] = "iOS" THEN [machine] = "iPhone";
+  `, true
+);
+
+make({machine, os, browser}, { // optional
+  preFilter: lexer.filter,
+});
+```
+
+```js
+[
+  { machine: 'ZenFone', browser: 'FireFox', os: 'Android' },
+  { os: 'Android', browser: 'Safari', machine: 'Pixel' },
+  { machine: 'Galaxy', browser: 'Chrome', os: 'Android' },
+  { machine: 'XPERIA', os: 'Android', browser: 'FireFox' },
+  { machine: 'Pixel', browser: 'Chrome', os: 'Android' },
+  { os: 'iOS', browser: 'FireFox', machine: 'iPhone' },
+  { machine: 'Pixel', browser: 'FireFox', os: 'Android' },
+  { os: 'iOS', browser: 'Chrome', machine: 'iPhone' },
+  { machine: 'Galaxy', browser: 'Safari', os: 'Android' },
+  { machine: 'ZenFone', browser: 'Chrome', os: 'Android' },
+  { os: 'iOS', browser: 'Safari', machine: 'iPhone' },
+  { machine: 'Galaxy', browser: 'FireFox', os: 'Android' },
+  { machine: 'XPERIA', browser: 'Chrome', os: 'Android' },
+  { machine: 'ZenFone', browser: 'Safari', os: 'Android' },
+  { machine: 'XPERIA', browser: 'Safari', os: 'Android' }
+]
+```
+
+This feature acts as a conversion tool that enables the implementation of PICT constraint conditions within CoverTable, 
+allowing users to seamlessly apply complex constraints to their test data generation.
+
+
+# Requirements
 
 ES2015 or later
 
@@ -179,6 +222,6 @@ $ npm version patch
 $ npm publish
 ```
 
-# More info
+# More information
 
 - [walkframe/covertable - GitHub](https://github.com/walkframe/covertable)

typescript/src/__tests__/filter.test.ts

@@ -1,13 +1,12 @@
-import { Dict, SuggestRowType } from "../types";
-import { make, makeAsync, sorters, criteria } from "../index";
+import { make, DictType, SuggestRowType } from "../";
 
 const machine = ["iPhone", "Pixel", "XPERIA", "ZenFone", "Galaxy"];
 const os = ["iOS", "Android"];
 const browser = ["FireFox", "Chrome", "Safari"];
 
 test('exclude impossible combinations', () => {
   const factors = {machine, os, browser};
-  const preFilter = (row: Dict) => {
+  const preFilter = (row: DictType) => {
     return !(
       (row.machine === 'iPhone' && row.os !== 'iOS') || 
       (row.machine !== 'iPhone' && row.os === 'iOS')
@@ -49,14 +48,14 @@ test('Limited to iphone and iOS combinations only.', () => {
 
 test('Use a constant-false function for preFilter', () => {
   const factors = {machine, os, browser};
-  const preFilter = (row: Dict) => false;
+  const preFilter = (row: DictType) => false;
   const rows = make(factors, { preFilter });
   expect(rows).toEqual([]);
 });
 
 test('Use the wrong conditional function for preFilter', () => {
   const factors = {machine, os, browser};
-  const preFilter = (row: Dict) => row.machine === 'WindowsPhone';
+  const preFilter = (row: DictType) => row.machine === 'WindowsPhone';
   const rows = make(factors, { preFilter });
   expect(rows).toEqual([]);
 });

typescript/src/__tests__/index.test.ts

@@ -1,6 +1,6 @@
 import { default as make, sorters, criteria } from '../index';
 import { product, combinations, range, len, all, getItems } from '../lib';
-import { FactorsType, Scalar, Dict, PairType } from '../types';
+import { FactorsType, ScalarType, DictType, PairType } from '../types';
 
 const getPairs = function* (factors: FactorsType, length = 2) {
   const allKeys = getItems(factors).map(([k, _]) => k);
@@ -69,7 +69,7 @@ test('prefilter excludes specified pairs before', () => {
     ["d", "e"],
     ["f"],
   ];
-  const preFilter = (row: Dict) => {
+  const preFilter = (row: DictType) => {
     if (row[0] === "a" && row[1] === "d") {
       return false;
     }
@@ -151,7 +151,7 @@ test('dict type factors make dict row', () => {
     'key5': ["m", "n", "o"],
   };
   const rows = make(factors);
-  const sorter = (a: Scalar, b: Scalar) => a > b ? 1 : -1;
+  const sorter = (a: ScalarType, b: ScalarType) => a > b ? 1 : -1;
   for (let row of rows) {
     const keys1 = Object.keys(row).sort(sorter);
     const keys2 = Object.keys(factors).sort(sorter);

typescript/src/controller.ts

@@ -17,9 +17,9 @@ import {
   IndicesType,
   FactorsType,
   SerialsType,
-  Scalar,
-  Dict,
-  PairByKey,
+  ScalarType,
+  DictType,
+  PairByKeyType,
   ParentsType,
   CandidateType,
   RowType,
@@ -29,9 +29,9 @@ import {
 } from "./types";
 import { NeverMatch, NotReady } from "./exceptions";
 
-export class Row extends Map<Scalar, number> implements RowType {
+export class Row extends Map<ScalarType, number> implements RowType {
   // index: number
-  public consumed: PairByKey = new Map();
+  public consumed: PairByKeyType = new Map();
 
   constructor(row: CandidateType) {
     super();
@@ -57,9 +57,9 @@ export class Controller<T extends FactorsType> {
   private serials: SerialsType = new Map();
   private parents: ParentsType = new Map();
   private indices: IndicesType = new Map();
-  public incomplete: PairByKey = new Map();
+  public incomplete: PairByKeyType = new Map();
 
-  private rejected: Set<Scalar> = new Set();
+  private rejected: Set<ScalarType> = new Set();
   public row: Row;
 
   constructor(public factors: FactorsType, public options: OptionsType<T>) {
@@ -169,8 +169,8 @@ export class Controller<T extends FactorsType> {
     return row.size === this.factorLength;
   }
 
-  toMap(row: Row): Map<Scalar, number[]> {
-    const result: Map<Scalar, number[]> = new Map();
+  toMap(row: Row): Map<ScalarType, number[]> {
+    const result: Map<ScalarType, number[]> = new Map();
     for (let [key, serial] of row.entries()) {
       const index = this.indices.get(serial) as number;
       const first = this.indices.get((this.serials.get(key) as PairType)[0]);
@@ -181,15 +181,15 @@ export class Controller<T extends FactorsType> {
   }
 
   toProxy(row: Row) {
-    const obj: Dict = {};
+    const obj: DictType = {};
     for (let [key, value] of this.toMap(row).entries()) {
       obj[key] = value;
     }
     return new Proxy(obj, proxyHandler) as SuggestRowType<T>;
   }
 
   toObject(row: Row) {
-    const obj: Dict = {};
+    const obj: DictType = {};
     for (let [key, value] of this.toMap(row).entries()) {
       obj[key] = value;
     }

typescript/src/criteria/greedy.ts

@@ -1,8 +1,8 @@
-import type {FactorsType, PairByKey, PairType} from '../types';
+import type {FactorsType, PairByKeyType, PairType} from '../types';
 import { combinations, unique } from '../lib';
 import { Controller } from '../controller';
 
-const getNumRemovablePairs = (indexes: Set<number>, incomplete: PairByKey, length: number) => {
+const getNumRemovablePairs = (indexes: Set<number>, incomplete: PairByKeyType, length: number) => {
   let num = 0;
   const removingKeys = combinations([... indexes], length);
   for (let pair of removingKeys) {