npmpackage.info

iterator-matcher

Easily found out if an ES6 Iterator match what you expected

2.1.0

MIT

TypeScript

Installations

npm install iterator-matcher

Pull Requests

Open

0

Total

111

Closed

78

Merged

33

Issues

Open

0

Total

2

Closed

2

Releases

v2.1.0

Published on 12 Sept 2023

v2.0.0

Published on 11 Dec 2022

v1.0.1

Published on 22 May 2022

View all 3 releases

Developer

fraxken

Developer Guide

BETA

Module System

CommonJS, ESM

Min. Node Version

Typescript Support

Yes

Node Version

20.6.1

NPM Version

9.8.1 Statistics

7 Stars

56 Commits

1 Forks

2 Watching

1 Branches

2 Contributors

Updated on 25 Nov 2024

Languages

TypeScript (100%)

Total Downloads

Cumulative downloads

Total Downloads

3,067

Last day

-33.3%

Compared to previous day

Last week

-6.7%

Compared to previous week

Last month

65.1%

Compared to previous month

Last year

169.8%

2,107

Compared to previous year

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dev Dependencies

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

Versions

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

Binary-Artifacts

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

10

CI-Tests

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

10

Contributors

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

10

Dangerous-Workflow

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

10

Dependency-Update-Tool

Determines if the project uses a dependency update tool.

10

License

Determines if the project has defined a license.

10

Maintained

Determines if the project is "actively maintained".

10

Pinned-Dependencies

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

10

Security-Policy

Determines if the project has published a security policy.

10

Token-Permissions

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

9

SAST

Determines if the project uses static code analysis.

9

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

0

CII-Best-Practices

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

0

Code-Review

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

0

Fuzzing

Determines if the project uses fuzzing.

Score

8.1

/10

Last Scanned on 2024-11-26T07:32:40Z

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

Other packages similar to iterator-matcher

jest-matcher-utils

29.7.0

A set of utility functions for expect and related packages

es-iterator-helpers

1.2.0

An ESnext spec-compliant iterator helpers shim/polyfill/replacement that works as far down as ES3.

es-get-iterator

1.1.3

Get an iterator for any JS language value. Works robustly across all environments, all versions.

stop-iteration-iterator

1.0.0

Firefox 17-26 iterators throw a StopIteration object to indicate "done". This normalizes it.