# xiter

> Extended iterables such as `Set`.

Latest version **1.1.0** (published 2019-12-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install xiter
pnpm add xiter
yarn add xiter
bun add xiter
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2019-12-04 |
| First published | 2019-12-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 25.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Kyle Lin |
| Maintainers | kylejlin |
| Keywords | typescript, es6, set, iterable, monad |

## Links

- npm: https://www.npmjs.com/package/xiter
- Repository: https://github.com/kylejlin/xiter
- Homepage: https://github.com/kylejlin/xiter#readme
- Issues: https://github.com/kylejlin/xiter/issues
- npm.io page: https://npm.io/package/xiter

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2019-12-04
- 1.0.0 — 2019-12-03

## README

# xiter - E**x**tended **iter**ables

[![Build Status](https://travis-ci.com/kylejlin/xiter.svg?branch=master)](https://travis-ci.com/kylejlin/xiter)
[![Coverage Status](https://coveralls.io/repos/github/kylejlin/xiter/badge.svg?branch=master)](https://coveralls.io/github/kylejlin/xiter?branch=master)
[![npm version](https://badge.fury.io/js/xiter.svg)](https://www.npmjs.com/package/xiter)
[![Downloads](https://img.shields.io/npm/dm/xiter.svg)](https://www.npmjs.com/package/xiter)

Extensions of ES6 iterables such as `Set`.

## Problem

Many iterables (such as `Set`, for instance) lack methods supporting common iterator operations (such as `map`, `filter`, `every`, etc.).

`Array` is the only iterable that currently provides all these methods. Consequently, in order to perform one of these operations on a non-`Array` iterable, one must convert the iterable into an `Array`, perform the operation, and convert it back to the original type of iterable.

For example, suppose you had the following `Set` and mapper function:

```typescript
const original: Set<string> = ...;
function mapper(s: string): number { ... }
```

Ideally, you would be able to write:

```typescript
const mapped = original.map(mapper);
```

...but in reality, you have to write:

```typescript
const mapped = new Set(Array.from(original).map(mapper));
```

Notice how much more readable the former is. If your codebase frequently performs these iterator operations, readability improvements like these will quickly add up.

Unfortunately, the former currently throws an error, because the native `Set` does not provide a `map` method.

## Solution

`xiter` provides thorougly tested and documented extensions of native iterables that provide these methods.

These extensions are _fully backwards-compatible_, allowing you to confidently replace any native iterables with their extended counterparts without fear of breaking your codebase.

## Usage

```bash
npm install --save xiter
```

```typescript
import { XSet } from "xiter";

const a = new XSet(["x", "y", "z"]);
const b = new XSet([8, "z", false]);

function printSet(s: Set<any>): void {
  console.log(Array.from(s));
}

// XSets behave like native Sets...

console.log(a instanceof Set); // true
console.log(a.has("z"), a.has("w")); // true, false;
console.log(a.delete("z"), a.delete("z")); // true, false
a.add("z");
console.log(a.size); // 3

// ...but have additional methods you would expect all iterables to have (e.g., map)...

printSet(a.map(s => s.toUpperCase())); // ["X", "Y", "Z"]
printSet(b.filter(x => "number" === typeof x)); // [8]
console.log(b.find(x => "number" === typeof x); // 8
console.log(b.some(x => "number" === typeof x); // true
console.log(b.every(x => "number" === typeof x); // false

// See API Docs for the rest of the methods.
```

## API Docs

Docs can be found [here](https://kylejlin.github.io/xiter/).

## ("Bonus") class-specific methods

As a bonus, some extensions provide additional class-specific methods for your convenience. For example, `XSet` provides methods implementing common set operations, such as `union` and `isSubsetOf`.

These methods, despite being completely unrelated to solving the original problem of providing iterator operations, were included as a part of this library because the author believed there is a reasonable chance that users of the given iterables would want to perform these class-specific operations in addition to the iterator operations.

## Roadmap

- ~~`XSet`~~ provided as of [v1.0.0](https://github.com/kylejlin/xiter/releases/tag/v1.0.0)
- `XMap`
- `XWeakSet`?
- `XWeakMap`?

## License

MIT

Copyright (c) 2019 Kyle Lin

---
_Source: https://npm.io/package/xiter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._