itiriri

Unlike standard JavaScript array methods that create shallow copies and execute immediately, itiriri functions that return iterables use deferred execution.

Key behaviors:

1. Lazy Evaluation: The source iterable is not processed until you chain a function that reduces the value (like .sum()) or transform it into a built-in type (like iterating with for...of).
2. Single Pass: The source iterable is iterated only once.
3. Memory Efficiency: Methods like filter, map, and concat do not buffer elements; they pipe them one-by-one through the chain.
4. Infinite Iterables: Because of deferred execution, you can use itiriri with infinite generators (e.g., a Fibonacci sequence) as long as you use a terminal method like .take(n) to limit the results.

Note: Functions that require the entire sequence to be known (like sort, reverse, or shuffle) expect a finite iterable.

import itiriri from 'itiriri';

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

// Finding first 3 Fibonacci numbers that contain '42'
// This works because .take(3) stops the iteration
const result = itiriri(fibonacci())
  .filter(x => x.toString().indexOf('42') !== -1)
  .take(3);

for (const e of result) {
  console.log(e);
}
// outputs: 514229, 267914296, 7778742049

The IterableQuery<T> interface is the primary consumer-facing abstraction in itiriri. It extends the standard Iterable<T> and provides a fluent, chainable API for performing complex operations on sequences. Because it inherits from multiple specialized interfaces (like IterableFilter, IterableTransformation, and IterableJoin), an IterableQuery object allows you to mix and match operations like filtering, mapping, joining, and set operations in a single pipeline.

Key characteristics:

• Chainability: Most methods return a new IterableQuery<T>, allowing for functional-style pipelines.
• Lazy/Deferred Execution: While the interface defines the operations, the actual computation is typically deferred until the sequence is consumed.
• Rich API: It combines standard iterator methods (keys, values, entries) with advanced sequence manipulation (concat, prepend, fill).

An IterableQuery<T> is a wrapper around an Iterable<T>. Most methods on the Itiriri class (like map, filter, take) are lazy: they return a new IterableQuery representing the transformation without immediately executing it. The actual iteration and computation occur only when you call a terminal method (a reducer or a cast) or manually iterate over the object using for...of or the [Symbol.iterator]() method.

Key distinction:

• Intermediate operations (e.g., map, filter, slice, skip) return a new IterableQuery and are lazy.
• Terminal operations (e.g., toArray, sum, first, forEach, reduce) execute the pipeline and return a concrete value or perform an action.

// Lazy pipeline construction
const query = itiriri([1, 2, 3, 4, 5])
  .filter(x => x % 2 === 0)
  .map(x => x * 10);

// Terminal operation triggers execution
const result = query.toArray(); // [20, 40]

The groupJoin method performs a join where each element from the source sequence is matched with an array of all elements from the joined sequence that share the same key. If no matches are found, the joinSelector is called with an empty array.

Note: groupJoin is a deferred method; it is only executed when the resulting sequence is iterated (e.g., by calling .toArray()).

import itiriri from 'itiriri';

const books = [
  {title: 'Clean code', categoryId: 1 },
  {title: 'Code complete', categoryId: 1},
  {title: 'Scrum', categoryId: 2},
];

const categories = [
  {id: 1, name: 'CS'},
  {id: 2, name: 'Agile'},
];

itiriri(categories).groupJoin(
  books,
  category => category.id,
  book => book.categoryId,
  (category, books) => ({ category: category.name, books: books.map(b => b.title) })
).toArray();
// [ 
//   {category: 'CS', books: ['Clean code', 'Code complete']},
//   {category: 'Agile', books: ['Scrum']}
// ]