npmpackage.info

Gathering detailed insights and metrics for iterator-matcher

Other packages similar to iterator-matcher

vitest-iterator

0.2.0

Additional vitest matchers for iterators and generators

Gathering detailed insights and metrics for iterator-matcher

iterator-matcher - 2.1.0 | npmpackage.info

iterator-matcher

Easily found out if an ES6 Iterator match what you expected

2.1.0

MIT

TypeScript

25.52 kB

8.1

Installations

npm install iterator-matcher

Developer Guide

BETA

Typescript

Yes

Module System

CommonJS, ESM

Node Version

20.6.1

NPM Version

9.8.1 Pull Requests

Open

0

Total

148

Closed

78

Merged

70

Issues

Open

0

Total

2

Closed

2

Releases

v2.1.0

Updated on Sep 12, 2023

v2.0.0

Updated on Dec 11, 2022

v1.0.1

Updated on May 22, 2022

View All 3 releases

Languages

TypeScript

JavaScript

TypeScript (99.53%)

JavaScript (0.47%)

Developer

fraxken

Download Statistics

Total Downloads

Last Day

Last Week

Last Month

Last Year

GitHub Statistics

MIT License

7 Stars

97 Commits

1 Forks

2 Watchers

1 Branches

2 Contributors

Updated on Jul 14, 2025

Maintainers

View All 2 Contributors

Package Meta Information

Latest Version

2.1.0

Package Id

iterator-matcher@2.1.0

Unpacked Size

25.52 kB

Size

5.69 kB

File Count

NPM Version

9.8.1

Node Version

20.6.1

Published on

Sep 12, 2023

Total Downloads

Cumulative downloads

Total Downloads

NaN

Last Day

NaN

Compared to previous day

Last Week

NaN

Compared to previous week

Last Month

NaN

Compared to previous month

Last Year

NaN

Compared to previous year

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dev Dependencies

@nodesecure/eslint-config @types/node c8 eslint glob tsup tsx typescript

iterator-matcher

Easily found out if an ES6 Iterator match what you expected

Limitations

No built-in mechanism to match on non-primitive values.

Requirements

Node.js v16 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

1$ npm i iterator-matcher
2# or
3$ yarn add iterator-matcher

Usage example

1import { IteratorMatcher } from "iterator-matcher";
2import assert from "node:assert";
3
4function* dummyGen() {
5  yield "console";
6  yield "trace";
7  yield "error";
8}
9
10const result = new IteratorMatcher()
11  .expect("console")
12  .expect(["trace", "error"], { occurence: 2 })
13  .execute(dummyGen());
14
15assert.ok(result.isMatching, true);
16assert.equal(result.elapsedSteps, 3);

[!NOTE] You can re-use the same IteratorMatcher multiple time.

API

constructor()

No options are required.

expect(expectedValue: T | T[] | Set< T >, options: IteratorMatcherExpectOptions): this

The options payload is described by the following TypeScript interface:

1export interface IteratorMatcherExpectOptions {
2  /**
3   * When a value is not mandatory the Executor continue his job/execution.
4   *
5   * @default true
6   */
7  mandatory?: boolean;
8  /**
9   * Number of occurences of the expected value
10   *
11   * @default 1
12   */
13  occurence?: number;
14}

In usage the expectedValue can be an Array or a ES6 Set.

1new IteratorMatcher()
2  .expect("primitive", { mandatory: false })
3  .expect([1, 2, 3])
4  .expect(new Set(["oh", "hey", "oh"]), { occurence: 2 });

execute(iterator: IterableIterator< T >, options: IteratorMatcherExecutorOptions): IteratorMatcherExecutorResult

The options payload is described by the following TypeScript interface:

1interface DefaultIteratorMatcherExecutorOptions {
2  /**
3   * Stop the executor on the first matching value.
4   *
5   * @default false
6   */
7  stopOnFirstMatch?: boolean;
8
9  /**
10   * When enabled it return isMatching: true if no value has been matched (like an empty Iterator for example).
11   *
12   * @default true
13   */
14  allowNoMatchingValues?: boolean;
15}
16
17interface DefaultUnpreservedIteratorMatcherExecutorOptions
18  extends DefaultIteratorMatcherExecutorOptions {
19  /**
20   * Authorize unexpected value to appear
21   *
22   * @default false
23   */
24  allowUnexpectedValue?: boolean;
25}
26
27export type IteratorMatcherExecutorOptions = {
28  /**
29   * When enabled it preserve the order of expectation
30   */
31  preserveExpectationOrder?: true;
32} & DefaultIteratorMatcherExecutorOptions | {
33  /**
34   * When disabled it will iterate all expectations and try to match them all with no order.
35   */
36  preserveExpectationOrder?: false;
37} & DefaultUnpreservedIteratorMatcherExecutorOptions;

The response is described by the following TypeScript type:

1export type IteratorMatcherExecutorResult = {
2  isMatching: boolean;
3  elapsedSteps: number;
4}

EventListener

The IteratorMatcher expose an additional EventListener helper class useful for testing purpose with Node.js EventEmitter.

Here a real world example extracted from the UT one of my package:

1import assert from "node:assert";
2import { test } from "node:test";
3
4import { TimeStore } from "@openally/timestore";
5import { IteratorMatcher, EventListener } from "iterator-matcher";
6
7test("Example with TimeStore, IteratorMatcher and EventListener", () => {
8  const store = new TimeStore({ ttl })
9  .add("foo").add("bar");
10  const eeListener = new EventListener(store, TimeStore.Expired);
11
12  // Doing some work with store
13
14  assert.equal(eeListener.listenerCount, 2);
15  const { isMatching } = new IteratorMatcher()
16    .expect("foo")
17    .expect("bar")
18    .execute(eeListener.names(), { allowNoMatchingValues: false });
19  assert.ok(isMatching, true);
20});

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_Gentilhomme
💻 🐛 📖 🛡️

License

MIT

No vulnerabilities found.

10

Maintained

Determines if the project is "actively maintained".

10

Dependency-Update-Tool

Determines if the project uses a dependency update tool.

10

Security-Policy

Determines if the project has published a security policy.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

10

Dangerous-Workflow

Determines if the project's GitHub Action workflows avoid dangerous patterns.

10

Pinned-Dependencies

Determines if the project has declared and pinned the dependencies of its build process.

10

Token-Permissions

Determines if the project's workflows follow the principle of least privilege.

10

SAST

Determines if the project uses static code analysis.

10

License

Determines if the project has defined a license.

10

Contributors

Determines if the project has a set of contributors from multiple organizations (e.g., companies).

10

CI-Tests

Determines if the project runs tests before pull requests are merged.

9

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

0

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Fuzzing

Determines if the project uses fuzzing.

Score

8.1

/10

Last Scanned on 2025-07-08T07:36:24Z

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More