0.4.10 • Published 6 months ago

@rustable/iter v0.4.10

Weekly downloads
-
License
MIT
Repository
github
Last release
6 months ago

@rustable/iter

A TypeScript library providing Rust-style iterator adapters with a rich set of functional operations for collection manipulation.

📖 Overview

@rustable/iter brings Rust's powerful iterator patterns to TypeScript, enabling functional, lazy, and composable operations on collections. It provides a rich set of iterator adapters that can be chained together to create complex data transformations with minimal overhead.

✨ Features

  • 🚀 Lazy Evaluation - Computations are performed only when needed
  • 🔗 Chainable API - Fluent interface for composing operations
  • 📦 Zero Dependencies - Lightweight and self-contained
  • 🛡️ Type Safe - Full TypeScript support with strong type inference
  • 🦀 Rust-Inspired - Familiar API for Rust developers
  • 🎯 Tree-Shakeable - Only import what you need

📦 Installation

npm install @rustable/iter

# or with yarn
yarn add @rustable/iter

# or with pnpm
pnpm add @rustable/iter

📖 Usage

import { iter, range } from '@rustable/iter';

// Basic transformations
iter([1, 2, 3, 4, 5])
  .map((x) => x * 2)
  .filter((x) => x > 5)
  .collect(); // [6, 8, 10]

// Working with strings
iter('hello').enumerate().collect(); // [[0, 'h'], [1, 'e'], [2, 'l'], [3, 'l'], [4, 'o']]

// Numeric ranges
range(0, 5)
  .map((x) => x * x)
  .collect(); // [0, 1, 4, 9, 16]

📗 API

Creation

  • iter(iterable) - Create iterator from any iterable
  • range(start, end, step?) - Create numeric range iterator

Transformation

  • map(fn) - Transform each element
  • filter(predicate) - Keep elements matching predicate
  • flatMap(fn) - Map and flatten results
  • flatten() - Flatten nested iterables

Subsetting

  • take(n) - Take first n elements
  • skip(n) - Skip first n elements
  • stepBy(n) - Take every nth element
  • takeWhile(predicate) - Take while predicate is true

Combining

  • zip(other) - Combine with another iterator
  • chain(other) - Append another iterator
  • interleave(other) - Alternate elements with another iterator

Grouping

  • groupBy(fn) - Group elements by key
  • uniq() - Remove consecutive duplicates
  • uniqBy(fn) - Remove duplicates by key

Terminal Operations

  • collect() - Collect into array
  • reduce(fn, initial?) - Reduce to single value
  • forEach(fn) - Execute for each element
  • find(predicate) - Find first matching element

🔥 Advanced Features

For more advanced iterator operations, you can import them from @rustable/iter/advanced:

import { iter } from '@rustable/iter';
import '@rustable/iter/advanced';

// Numeric operations
iter([1, 2, 3, 4]).sum(); // 10
iter([1, 2, 3, 4]).product(); // 24

// Comparison operations
iter([1, 4, 2, 3]).max(); // Some(4)
iter([1, 4, 2, 3]).min(); // Some(1)

// Partitioning
iter([1, 2, 3, 4, 5])
  .partition(x => x % 2 === 0); // [[2, 4], [1, 3, 5]]

// Chunking
iter([1, 2, 3, 4])
  .chunks(2); // [[1, 2], [3, 4]]

// Windows
iter([1, 2, 3, 4])
  .windows(2); // [[1, 2], [2, 3], [3, 4]]

// Scanning
iter([1, 2, 3])
  .scan(0, (sum, x) => sum + x); // [1, 3, 6]

// Grouping
iter([1, 1, 2, 3, 3])
  .groupBy(x => x); // [[1, [1, 1]], [2, [2]], [3, [3, 3]]]

These advanced features are separated to keep the core package lightweight. Import them only when needed.

📚 Examples

Lazy Evaluation

const iter = iter([1, 2, 3, 4, 5])
  .map((x) => {
    console.log(`Processing ${x}`);
    return x * 2;
  })
  .filter((x) => x > 5);

// Nothing logged yet - no processing has occurred
const result = iter.collect(); // Now the processing happens

Complex Transformations

// Process user data
interface User {
  id: number;
  name: string;
  age: number;
}

const users: User[] = [
  /* ... */
];

iter(users)
  .filter((user) => user.age >= 18)
  .map((user) => ({
    id: user.id,
    displayName: user.name.toUpperCase(),
  }))
  .groupBy((user) => user.id)
  .collect();

// String processing
iter('Hello World!')
  .flatMap((s) => s.split(' '))
  .map((s) => s.toLowerCase())
  .filter((s) => s.length > 3)
  .collect(); // ['hello', 'world']

// Generate Fibonacci sequence
function* fibonacci() {
  let [a, b] = [0, 1];
  while (true) {
    yield a;
    [a, b] = [b, a + b];
  }
}

iter(fibonacci()).take(10).collect(); // [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

📄 License

MIT © Illuxiza

0.4.10

6 months ago

0.4.9

6 months ago

0.4.8

6 months ago

0.4.7

9 months ago

0.4.4

9 months ago

0.4.2

9 months ago

0.4.1

9 months ago

0.4.0

9 months ago

0.3.17

9 months ago

0.3.16

9 months ago

0.3.15

9 months ago

0.3.14

9 months ago

0.3.13

9 months ago

0.3.12

9 months ago

0.3.11

9 months ago

0.3.10

9 months ago

0.3.9

9 months ago

0.3.8

10 months ago

0.3.7

10 months ago

0.3.6

10 months ago

0.3.5

10 months ago

0.3.4

10 months ago

0.3.3

10 months ago

0.3.2

10 months ago

0.3.1

10 months ago

0.3.0

10 months ago

0.2.11

10 months ago

0.2.10

10 months ago

0.2.9

10 months ago

0.2.8

10 months ago

0.2.7

10 months ago

0.2.6

10 months ago

0.2.5

10 months ago

0.2.4

10 months ago

0.2.3

10 months ago

0.2.2

10 months ago

0.2.1

10 months ago

0.2.0

10 months ago

0.1.7

10 months ago

0.1.6

10 months ago

0.1.5

10 months ago

0.1.4

11 months ago

0.1.3

11 months ago

0.1.2

11 months ago

0.1.0-alpha.2

11 months ago

0.1.0-alpha.1

11 months ago

0.0.9

11 months ago