feat: add predicate filter (#21)

## Custom filter predicate

You can filter the items by passing a predicate function

```js
it.each(items, (x, k) => ...)
// creates a test for every item the predicate returns a truthy value
```

README.md

@@ -188,6 +188,15 @@ it.each(items, 3, 1)(...)
 it.each(items, 3, 2)(...)
 ```
 
+## Custom filter predicate
+
+You can filter the items by passing a predicate function
+
+```js
+it.each(items, (x, k) => ...)
+// creates a test for every item the predicate returns a truthy value
+```
+
 ## Exclusive tests
 
 Normally you could run just a selected test using `it.only` or a suite of tests using `describe.only`. Similarly, you could skip a single test or a suite of tests using `it.skip` and `describe.skip` methods. These methods are NOT supported by `it.each` and `describe.each`. Thus if you want to only run the `it.each` tests, surround it with its own `describe` block.

cypress/integration/filter-spec.js

@@ -0,0 +1,19 @@
+// @ts-check
+/// <reference types="cypress" />
+
+import '../../src'
+
+describe('filter function', () => {
+  const items = [1, 2, 3, 4]
+
+  it.each(items, (x, k) => x === 4)('only the last item matches %d', (x) => {
+    expect(x).to.equal(4)
+  })
+
+  it.each(items, (x, k) => k === 1)(
+    'only allows the 2nd item by index %d',
+    (x) => {
+      expect(x).to.equal(2)
+    },
+  )
+})

src/index.d.ts

@@ -3,6 +3,7 @@
 // https://github.com/bahmutov/cypress-each
 
 type TestTitleFn<T> = (item: T, index: number, items: T[]) => string
+type ItemPredicateFunction<T> = (item: T, index: number, items: T[]) => boolean
 
 declare namespace Mocha {
   type TestCallback<T> = (this: Context, arg0: T, arg1: any, arg2: any) => void
@@ -12,14 +13,14 @@ declare namespace Mocha {
      * Iterates over each given item (optionally chunked), and creates
      * a separate test for each one.
      * @param values Input items to create the tests form OR number of times to repeat a test
-     * @param totalChunks (Optional) number of chunks to split the items into
+     * @param totalChunks (Optional) number of chunks to split the items into, or Nth filter, or a predicate function
      * @param chunkIndex (Optional) index of the chunk to get items from
      * @example it.each([1, 2, 3])('test %K', (x) => ...)
      * @see https://github.com/bahmutov/cypress-each
      */
     each<T = unknown>(
       values: T[] | number,
-      totalChunks?: number,
+      totalChunks?: number | ItemPredicateFunction<T>,
       chunkIndex?: number,
     ): (titlePattern: string | TestTitleFn<T>, fn: TestCallback<T>) => void
   }

src/index.js

@@ -72,6 +72,9 @@ if (!it.each) {
       ) {
         // take every Nth item
         values = values.filter((_, k) => k % totalChunks === 0)
+      } else if (typeof totalChunks === 'function') {
+        // filter using the given predicate
+        values = values.filter(totalChunks)
       }
 
       values.forEach(function (value, k) {