@shun-shobon/iter-funcs

iter-funcs

About

Utility functions for iterators. Inspired by Rust's std::iter::Iterator trait. This library uses JavaScript native iterators, so it's compatible with any library that uses them.

Support platforms

• Node.js
• Deno
• Browser

Installation

Node.js

Install package from npm.

npm install @shun-shobon/iter-funcs@1.7.0

You can import from the package as @shun-shobon/iter-funcs.

import { filter, map } from "@shun-shobon/iter-funcs";

Deno

You can directly import from deno.land/x.

import { filter, map } from "https://deno.land/x/iter_funcs@1.7.0/mod.ts";

Browser

You can directly import from unpkg.com.

import {
  filter,
  map,
} from "https://unpkg.com/@shun-shobon/iter-funcs@1.7.0/esm/mod.js";

Example

This is a basic example.

import {
  filter,
  forEach,
  fromIterable,
  map,
  pipe,
  take,
} from "https://deno.land/x/iter_funcs@1.7.0/mod.ts";

const array = [1, 2, 3, 4, 5, 6];

pipe(
  array,
  fromIterable, // make iterator from iterable
  filter((x) => x % 2 === 0), // filter even numbers
  map((x) => x * 2), // multiply by 2
  take(2), // take first 2 elements
  forEach(console.log), // => 4, 8
);

You can also AsyncIterator.

import { expandGlob } from "https://deno.land/std/fs/mod.ts";
import {
  asyncFilter,
  asyncForEach,
  asyncMap,
  asyncTake,
  asyncToArray,
  pipe,
} from "https://deno.land/x/iter_funcs@1.7.0/mod.ts";

const files: Array<string> = await pipe(
  expandGlob("src/*.ts"), // Find all .ts files in src directory
  asyncMap((entry) => entry.path), // Get path from entry
  asyncFilter((path) => !path.endsWith("_test.ts")), // Exclude test files
  asyncTake(2), // Take first 2 elements
  asyncMap((path) => Deno.readTextFile(path)), // Read file content
  asyncToArray, // Convert to array
);

Difference from Array.prototype methods

This library's functions are lazy. They don't evaluate the whole iterator at once. They evaluate only the needed elements. This is useful when you have a large iterator and you only need a few elements from it.

Why not use method chaining?

Method chaining is a common pattern in JavaScript. However, it tends to increase bundle size. It also makes it difficult to use with other libraries that use iterators.

Changelog

1.7.0 (2022-12-27)

Features

• Add stepBy (177c754)
• Add toArray (8ac0aec)

Bug Fixes

• Fix main field of package.json (1e98c8a)
• Use PromiseLike instead of Promise (feed517)