### Install itiriri using npm

Source: https://labs42io.github.io/itiriri

Standard npm installation command for the itiriri library.

```bash
$ npm install 'itiriri' --save
```

--------------------------------

### Run Tests for itiriri

Source: https://labs42io.github.io/itiriri

Commands to install dependencies and run the test suite for the itiriri library.

```bash
$ npm install
$ npm test
```

--------------------------------

### Use itiriri in the Browser

Source: https://labs42io.github.io/itiriri

Example of including the bundled itiriri.min.js file and using itiriri with an array in a web page.

```html
<script src="itiriri.min.js"></script>
<!-- ... -->
<script>
    // source can be an array or an Iterable
    const source = [1, 2, 3];
    console.log(itiriri(source).sum());
</script>
```

--------------------------------

### Bundle itiriri for Browser Usage

Source: https://labs42io.github.io/itiriri

Instructions to install dependencies and run the Gulp task to create a minified browser-ready JavaScript file.

```bash
$ npm install
$ gulp bundle
// creates itiriri.min.js file in the root folder
```

--------------------------------

### fill

Source: https://labs42io.github.io/itiriri

Returns a sequence filled from a start index to an end index with a static value. The end index is not included. This is a deferred method.

```APIDOC
## fill

### Description
Returns a sequence filled from a start index to an end index with a static value. The end index is not included.

### Syntax
```javascript
fill(value: T): IterableQuery<T>;
fill(value: T, start: number): IterableQuery<T>;
fill(value: T, start: number, end: number): IterableQuery<T>;
```

### Parameters
* `value` - _(required)_ value to fill
* `start` - _(optional)_ start index, defaults to 0
* `end` - _(optional)_ end index, defaults to sequence length

### Example
```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3, 4, 5]).fill([7]).toArray(); // returns [7, 7, 7, 7, 7]
itiriri([1, 2, 3, 4, 5]).fill([7, 3]).toArray(); // returns [1, 2, 3, 7, 7]
itiriri([1, 2, 3, 4, 5]).fill([7, 1, 3]).toArray(); // returns [1, 7, 7, 4, 5]
```

`fill` is a deferred method and is executed only when the result sequence is iterated.
```

--------------------------------

### Get the first element of a sequence

Source: https://labs42io.github.io/itiriri

Returns the first element of the sequence. For an empty sequence, it returns undefined.

```typescript
import itiriri from 'itiriri';

itiriri(['a', 'b', 'c']).first(); // returns 'a'
itiriri([]).first(); // returns undefined
```

--------------------------------

### slice

Source: https://labs42io.github.io/itiriri

Returns a new sequence representing a range of elements from a start index up to, but not including, an end index. If only a start index is provided, it extracts elements from that index to the end of the sequence.

```APIDOC
## `slice`

### Description
Returns a new sequence representing a range of elements from a start index up to, but not including, an end index. If only a start index is provided, it extracts elements from that index to the end of the sequence.

### Syntax
```typescript
slice(start: number): IterableQuery<T>;
slice(start: number, end: number): IterableQuery<T>;
```

### Parameters
* `start` - _(required)_ zero-based index at which to begin extraction
* `end` - _(optional)_ zero-based index before which to end extraction

### Example
```typescript
import itiriri from 'itiriri';

itiriri([1, 2, 3, 4, 5]).slice(1, 3).toArray(); // returns [2, 3]
```
```

--------------------------------

### Get Key-Value Entries of Sequence

Source: https://labs42io.github.io/itiriri

Returns a sequence of key/value pairs for each element and its index. This is a deferred method, executed only when the result is iterated.

```typescript
import itiriri from 'itiriri';

itiriri(['Alice', 'Bob', 'David']).entries().toArray();
// returns [[0, 'Alice'], [1, 'Bob'], [2, 'David']]
```

--------------------------------

### Get Sequence Keys (Indices)

Source: https://labs42io.github.io/itiriri

Use `keys` to generate a sequence of numbers representing the indices of the source sequence. This is a deferred method, executed upon iteration.

```typescript
import itiriri from 'itiriri';

itiriri(['a', 'b', 'c']).keys().toArray(); // returns [0, 1, 2]
```

--------------------------------

### Convert sequence to string with toString

Source: https://labs42io.github.io/itiriri

Use `toString` to get a string representation of the sequence. Elements are converted to strings and joined by a comma. Handles null values by inserting empty strings.

```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3]).toString(); // returns 1,2,3
```

```javascript
import itiriri from 'itiriri';

itiriri([1, null, 3]).toString(); // returns 1,,3
```

```javascript
import itiriri from 'itiriri';

itiriri([{value: 1}, {value: 2}]).toString(); // returns [object Object],[object Object]
```

--------------------------------

### Skip Elements from Sequence Start with skip

Source: https://labs42io.github.io/itiriri

The skip method removes a specified number of elements from the beginning of a sequence. It handles counts larger than the sequence length by returning an empty sequence and negative counts by skipping from the end. This method is deferred and executed upon iteration.

```typescript
import itiriri from 'itiriri';

itiriri([1, 2, 3, 4, 5]).skip(2).toArray(); // [3, 4, 5]
itiriri([1, 2, 3, 4, 5]).skip(10).toArray(); // []
itiriri([1, 2, 3, 4, 5]).skip(-2).toArray(); // [1, 2, 3]
```

--------------------------------

### Fill sequence with a static value

Source: https://labs42io.github.io/itiriri

Fills a sequence with a static value from a start index up to, but not including, an end index. The operation is deferred and executed upon iteration.

```typescript
import itiriri from 'itiriri';

itiriri([1, 2, 3, 4, 5]).fill([7]).toArray(); // returns [7, 7, 7, 7, 7]
itiriri([1, 2, 3, 4, 5]).fill([7, 3]).toArray(); // returns [1, 2, 3, 7, 7]
itiriri([1, 2, 3, 4, 5]).fill([7, 1, 3]).toArray(); // returns [1, 7, 7, 4, 5]
```

--------------------------------

### Get all values from an iterable

Source: https://labs42io.github.io/itiriri

Use the values() method to retrieve all elements from an iterable. This method is deferred and executes only when the result sequence is iterated, for example, by calling toArray().

```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3]]).values().toArray(); // returns [1, 2, 3]
```

--------------------------------

### Extract a Range of Elements with slice

Source: https://labs42io.github.io/itiriri

The slice method extracts a portion of the sequence from a start index up to, but not including, an end index. If only a start index is provided, it extracts to the end of the sequence. This method is deferred and executed upon iteration.

```typescript
import itiriri from 'itiriri';

itiriri([1, 2, 3, 4, 5]).slice(1, 3).toArray(); // returns [2, 3]
```

--------------------------------

### forEach

Source: https://labs42io.github.io/itiriri

Runs through every element and applies a given function. This method executes immediately.

```APIDOC
## forEach(action: (element: T, index: number) => void): void;

### Description
Runs through every element and applies a given function.

### Parameters
* `action` - _(required)_ function to apply on each element, accepts two arguments:
  * `element` - the current element
  * `index` - the index of the current element

### Example
```javascript
import itiriri from 'itiriri';
itiriri([1, 2, 3]).forEach(elem => console.log(elem));
// 1
// 2
// 3
```
```

--------------------------------

### take

Source: https://labs42io.github.io/itiriri

Returns a specified number of elements from the beginning of the sequence. If a negative count is specified, elements are taken from the end.

```APIDOC
## `take`

Returns a specified number of elements from the beginning of sequence.

### Syntax
```
take(count: number): IterableQuery<T>;
```

### Parameters
* `count` - _(required)_ number of elements to take

If a negative count is specified, returns elements from the end of the sequence.

### Example
```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3]).take(2); // returns [1, 2]
itiriri([1, 2, 3]).take(-2); // returns [2, 3]
itiriri([1, 2, 3]).take(10); // returns [1, 2, 3]
```

`take` _is a deferred method and is executed only when the result sequence is iterated._
```

--------------------------------

### prepend

Source: https://labs42io.github.io/itiriri

Returns a new sequence with the given elements added to the beginning of the original sequence. This is a deferred method.

```APIDOC
## prepend

### Description
Returns a sequence with given elements at the beginning.

### Syntax
```typescript
prepend(other: Iterable<T>): IterableQuery<T>;
prepend(other: T): IterableQuery<T>;
```

### Parameters
#### Path Parameters
- **other** (Iterable<T> | T) - Required - the sequence or element to be added at the beginning

### Remarks
`prepend` is a deferred method and is executed only when the result sequence is iterated.

### Example
```typescript
import itiriri from 'itiriri';

itiriri([1, 2, 3]).prepend([9, 10]).toArray(); // returns [1, 2, 3, 9, 10]
```
```

--------------------------------

### Get Last Element of Sequence

Source: https://labs42io.github.io/itiriri

Use `last` to retrieve the final element of a sequence. Returns `undefined` if the sequence is empty.

```typescript
import itiriri from 'itiriri';

itiriri(['a', 'b', 'c']).last(); // returns 'c'
itiriri([]).last(); // returns undefined
```

--------------------------------

### first

Source: https://labs42io.github.io/itiriri

Returns the first element in a sequence. Returns undefined for an empty sequence.

```APIDOC
## first

### Description
Returns the first element in a sequence.

### Syntax
```javascript
first(): T;
```

For an empty sequence returns `undefined`.

### Example
```javascript
import itiriri from 'itiriri';

itiriri(['a', 'b', 'c']).first(); // returns 'a'
itiriri([]).first(); // returns undefined
```
```

--------------------------------

### Get Unique Elements from Sequence

Source: https://labs42io.github.io/itiriri

Returns a sequence containing only unique elements. This is a deferred method, executed only when the result is iterated.

```typescript
import itiriri from 'itiriri';

itiriri([1, 42, 3, 4, 1]).distinct().toArray();  // returns [1, 42, 3, 4]
```

--------------------------------

### Take elements from sequence start/end with `take`

Source: https://labs42io.github.io/itiriri

Retrieves a specified number of elements from the beginning of a sequence. Negative counts retrieve elements from the end. This method is deferred.

```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3]).take(2); // returns [1, 2]
itiriri([1, 2, 3]).take(-2); // returns [2, 3]
itiriri([1, 2, 3]).take(10); // returns [1, 2, 3]
```

--------------------------------

### Create a Map with toMap

Source: https://labs42io.github.io/itiriri

Use `toMap` to create a Map from elements using `keySelector`. If a `valueSelector` is provided, it transforms the values. Throws an error if duplicate keys are encountered.

```javascript
import itiriri from 'itiriri';

itiriri(['a', 'b', 'c']).toMap(elem => elem.charCodeAt(0));
// returns Map {97 => 'a', 98 => 'b', 99 => 'c'}
```

```javascript
import itiriri from 'itiriri';

itiriri(['a', 'b', 'c']).toMap(elem => elem.charCodeAt(0), elem => elem.toUpperCase());
// returns Map {97 => 'A', 98 => 'B', 99 => 'C'}
```

```javascript
import itiriri from 'itiriri';

itiriri([1, 1]).toMap(elem => elem);
// throws an Error
```

--------------------------------

### Create a Set with toSet

Source: https://labs42io.github.io/itiriri

Use `toSet` to create a JavaScript Set from elements. An optional `selector` can transform elements before adding them to the Set.

```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3, 1, 3]).toSet(); // returns Set {1, 2, 3}
```

```javascript
import itiriri from 'itiriri';

itiriri([{value: 1}, {value: 2}, {value: 1}])
  .toSet(elem => elem.value); // returns Set {1, 2}
```

--------------------------------

### Iterate and perform actions with forEach

Source: https://labs42io.github.io/itiriri

The `forEach` method iterates over each element in the sequence and applies a given action function. The action function receives the current element and its index. This method has a void return type.

```javascript
import itiriri from 'itiriri';
itiriri([1, 2, 3]).forEach(elem => console.log(elem));
// 1
// 2
// 3
```

--------------------------------

### Deferred Execution with Fibonacci Sequence

Source: https://labs42io.github.io/itiriri

Illustrates deferred execution by filtering an infinite Fibonacci sequence for numbers containing '42' and taking the first three.

```javascript
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
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
```

--------------------------------

### Get Element by Index with nth

Source: https://labs42io.github.io/itiriri

Retrieves an element at a specific index. Supports negative indices for counting from the end. Returns undefined if the index is out of bounds.

```typescript
import itiriri from 'itiriri';

itiriri(['a', 'b', 'c', 'd']).nth(2)  // returns 'c'
itiriri(['a', 'b', 'c', 'd']).nth(-1) // returns 'd'
itiriri(['a', 'b', 'c', 'd']).nth(10) // returns undefined
```

--------------------------------

### toSet

Source: https://labs42io.github.io/itiriri

Creates a set of elements from the sequence, optionally transforming each element.

```APIDOC
## toSet

### Description
Creates a set of elements from the sequence, optionally transforming each element.

### Syntax
```javascript
toSet(): Set<T>;
toSet<S>(selector: (element: T, index: number) => S): Set<S>;
```

### Parameters
* `selector` - _(optional)_ A transformer function to apply to each element to get its value. Accepts two arguments: `element` (the current element) and `index` (the index of the current element).

### Example
```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3, 1, 3]).toSet(); // returns Set {1, 2, 3}
itiriri([{value: 1}, {value: 2}, {value: 1}])
  .toSet(elem => elem.value); // returns Set {1, 2}
```
```

--------------------------------

### Get Sequence Length

Source: https://labs42io.github.io/itiriri

The length method returns the total number of elements in a sequence. An optional predicate can be provided to count only elements that satisfy a condition.

```typescript
import itiriri from 'itiriri';

itiriri([1, 2, 3, 4, 5]).length();  // returns 5
```

```typescript
import itiriri from 'itiriri';

itiriri([1, 2, 3, 4, 5]).length(elem => elem > 2);  // returns 3
```

--------------------------------

### Get Unique Elements Using Selector

Source: https://labs42io.github.io/itiriri

Returns a sequence of unique elements based on a selector function. This is a deferred method, executed only when the result is iterated.

```typescript
import itiriri from 'itiriri';

itiriri([{value: 1}, {value: 2}, {value: 1}])
  .distinct(elem => elem.value)
  .toArray(); // returns [{value: 1}, {value: 2}]
```

--------------------------------

### Import itiriri in ES6 Modules

Source: https://labs42io.github.io/itiriri

How to import the itiriri library when using ES6 module syntax.

```javascript
import itiriri from 'itiriri';
```

--------------------------------

### every

Source: https://labs42io.github.io/itiriri

Tests whether all elements in the sequence satisfy a given predicate function.

```APIDOC
## every

### Description
Tests whether all the elements pass the predicate.

### Syntax
```typescript
every(predicate: (element: T, index: number) => boolean): boolean;
```

### Parameters
* `predicate` - _(required)_ function to test for each element 
  * `element` - the current element
  * `index` - the index of the current element
  * returns `true` or `false`

### Example
```typescript
import itiriri from 'itiriri';

itiriri([2, 4, 9]).every(elem => elem > 0); // returns true
itiriri([7, 23, 3]).every(elem => elem % 3 === 0); // returns false
```
```

--------------------------------

### toMap

Source: https://labs42io.github.io/itiriri

Creates a map of elements by a given key. If duplicate keys exist, an error is thrown.

```APIDOC
## toMap

### Description
Creates a map of elements by a given key. If duplicate keys exist, an error is thrown.

### Syntax
```javascript
toMap<M>(keySelector: (element: T, index: number) => M): Map<M, T>;
toMap<M, N>(keySelector: (element: T, index: number) => M, valueSelector: (element: T, index: number) => N): Map<M, N>;
```

### Parameters
* `keySelector` - _(required)_ A transformer function to apply to each element to get its key. Accepts two arguments: `element` (the current element) and `index` (the index of the current element).
* `valueSelector` - _(optional)_ A transformer function to apply to each element. Accepts two arguments: `element` (the current element) and `index` (the index of the current element).

### Example
```javascript
import itiriri from 'itiriri';

itiriri(['a', 'b', 'c']).toMap(elem => elem.charCodeAt(0));
// returns Map {97 => 'a', 98 => 'b', 99 => 'c'}

itiriri(['a', 'b', 'c']).toMap(elem => elem.charCodeAt(0), elem => elem.toUpperCase());
// returns Map {97 => 'A', 98 => 'B', 99 => 'C'}

itiriri([1, 1]).toMap(elem => elem);
// throws an Error
```
```

--------------------------------

### keys

Source: https://labs42io.github.io/itiriri

Returns a sequence of keys (indices) for each element in the source sequence. This is a deferred method.

```APIDOC
## keys

### Description
Returns a sequence of keys for each index in the source sequence. This is a deferred method and is executed only when the result sequence is iterated.

### Syntax
```javascript
keys(): IterableQuery<number>;
```

### Example
```javascript
import itiriri from 'itiriri';

itiriri(['a', 'b', 'c']).keys().toArray(); // returns [0, 1, 2]
```
```

--------------------------------

### Check if Sequence Includes Element

Source: https://labs42io.github.io/itiriri

Use `includes` to determine if a sequence contains a specific element. It uses strict equality (`===`) for comparisons. An optional `fromIndex` can specify the starting point for the search.

```typescript
import itiriri from 'itiriri';

itiriri([1, 2, 3]).includes(2); // returns true
itiriri([1, 2, 3]).includes(0); // returns false
```

--------------------------------

### entries

Source: https://labs42io.github.io/itiriri

Returns a sequence of key-value pairs, where each pair consists of an element's index and the element itself. This is a deferred method.

```APIDOC
## entries

### Description
Returns a sequence of key/value pair for each element and its index.

### Syntax
```typescript
entries(): IterableQuery<[number, T]>;
```

### Example
```typescript
import itiriri from 'itiriri';

itiriri(['Alice', 'Bob', 'David']).entries().toArray();
// returns [[0, 'Alice'], [1, 'Bob'], [2, 'David']]
```

`entries` _is a deferred method and is executed only when the result sequence is iterated._
```

--------------------------------

### Find Last Index of Element

Source: https://labs42io.github.io/itiriri

Use `lastIndexOf` to find the last occurrence of an element in a sequence. It returns `-1` if the element is not found. Strict equality (`===`) is used for comparison. The search can start from an optional `fromIndex`.

```typescript
import itiriri from 'itiriri';

itiriri(['a', 'c', 'c']).lastIndexOf('c'); // returns 2
itiriri(['a', 'b', 'c']).lastIndexOf('x'); // returns -1
```

--------------------------------

### Use itiriri with a Generator Function

Source: https://labs42io.github.io/itiriri

Demonstrates chaining map, take, and sum operations on a generator function. The result approximates Pi.

```javascript
function* numbers() {
  let n = 1;

  while (true) {
    yield n++;
  }
}

const s = itiriri(numbers()).map(n => 1 / (n * n)).take(1000).sum();
console.log(Math.sqrt(6 * s));
// 3.1406380562059946
```

--------------------------------

### Find First Index of Element

Source: https://labs42io.github.io/itiriri

Use `indexOf` to find the first occurrence of an element in a sequence. It returns `-1` if the element is not found. Strict equality (`===`) is used for comparison. The search can start from an optional `fromIndex`.

```typescript
import itiriri from 'itiriri';

itiriri(['a', 'b', 'c']).indexOf('c'); // returns 2
itiriri(['a', 'b', 'c']).indexOf('x'); // returns -1
```

--------------------------------

### Prepend Elements to Sequence

Source: https://labs42io.github.io/itiriri

Adds given elements or an iterable to the beginning of a sequence. This is a deferred method, executed upon iteration.

```typescript
import itiriri from 'itiriri';

itiriri([1, 2, 3]).prepend([9, 10]).toArray(); // returns [1, 2, 3, 9, 10]
```

--------------------------------

### Use itiriri with an Array

Source: https://labs42io.github.io/itiriri

Applies map and reverse operations to an array using itiriri. Demonstrates toString and iteration.

```javascript
import itiriri from 'itiriri';

const values = [2, 0, 4, 8];

const s = itiriri(values).map(n => n / 2).reverse();
console.log(s.toString()); // prints: 4,2,0,1

// prints: 4 2 0 1
for (const n of s) {
  console.log(n)
}

console.log(s.sum()); // prints: 7
```

--------------------------------

### toString

Source: https://labs42io.github.io/itiriri

Returns a string representation of the sequence by joining the string representation of each element with a comma.

```APIDOC
## toString

### Description
Returns a string representation of the sequence by joining the string representation of each element with a comma.

### Syntax
```javascript
toString(): string;
```

### Example
```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3]).toString(); // returns 1,2,3
itiriri([1, null, 3]).toString(); // returns 1,,3
itiriri([{value: 1}, {value: 2}]).toString(); // returns [object Object],[object Object]
```
```

--------------------------------

### Take elements while predicate is true with `takeWhile`

Source: https://labs42io.github.io/itiriri

Returns elements from the beginning of a sequence as long as they satisfy the provided predicate. This method is deferred.

```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3]).takeWhile(() => true); // returns [1, 2, 3]
itiriri([1, 2, 3]).takeWhile(() => false); // returns []
itiriri([1, 2, 3]).takeWhile(e => e < 3); // returns [1, 2]
itiriri([1, 2, 3]).takeWhile(e => e % 2 === 0); // returns []
```

--------------------------------

### Perform SQL-like Right Join with itiriri

Source: https://labs42io.github.io/itiriri

Use rightJoin to combine elements from two sequences based on a key. When an element from the right sequence has no match in the left, the left element is passed as undefined. This method is deferred and executed upon iteration.

```typescript
import itiriri from 'itiriri';

itiriri([1, 2, 3])
  .rightJoin([2, 3, 4, 2], n => n, n => n, (a, b) => `${a || '#'}-${b}`)
  .toArray();
// returns ['2-2', '3-3', '#-4', '2-2']
```

```typescript
import itiriri from 'itiriri';

itiriri([{book: 'History', owner: 3}, {book: 'Math', owner: 2}]])
  .rightJoin(
    [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Eve'}],
    right => right.id,
    left => left.owner,
    (right, left) => ({student: right.name, book: left && left.book || '--'}))
  .toArray();
// returns [
//   {student: 'Alice', book: '--'},
//   {student: 'Bob', book: 'Math'},
//   {student: 'Eve', book: 'History'}]
```

--------------------------------

### find

Source: https://labs42io.github.io/itiriri

Finds the first element that satisfies the specified predicate. Returns undefined if no element satisfies the predicate.

```APIDOC
## find

### Description
Finds the first element that satisfies the specified predicate.

### Syntax
```javascript
find(predicate: (element: T, index: number) => boolean): T;
```

### Parameters
* `predicate` - _(required)_ function to test for each element, accepts two arguments: 
  * `element` - the current element
  * `index` - the index of the current element
  * returns `true` if element satisfies the predicate, `false` otherwise

If no element satisfies the predicate, returns `undefined`.

### Example
```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3, 4, 5]).find(elem => elem % 2 === 0); // returns 2
itiriri([1, 2, 3]).find(elem > 10); // returns undefined
```
```

--------------------------------

### join

Source: https://labs42io.github.io/itiriri

Performs an inner join operation between the source sequence and another sequence based on specified key selectors.

```APIDOC
## join

### Description
Returns a sequence of correlated elements transformation that match a given key, similar to an SQL inner join. This is a deferred method, executed only when the result sequence is iterated.

### Syntax
```javascript
join<TKey, TRight, TResult>(
    other: Iterable<TRight>,
    leftKeySelector: (element: T, index: number) => TKey,
    rightKeySelector: (element: TRight, index: number) => TKey,
    joinSelector: (left: T, right: TRight) => TResult,
  ): IterableQuery<TResult>;
```

### Parameters
* `other` - (required) sequence to join
* `leftKeySelector` - (required) function that provides the key of each element from the source sequence. Accepts two arguments: `element` (the current element) and `index` (the index of the current element). Returns the element's key.
* `rightKeySelector` - (required) function that provides the key of each element from the joined sequence. Accepts two arguments: `element` (the current element) and `index` (the index of the current element). Returns the element's key.
* `joinSelector` - (required) a transformation function to apply on each matched tuple. Accepts two arguments: `left` (element from the source sequence) and `right` (element from the joined sequence). Returns a new result.

### Example
```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3])
  .join([2, 3, 4], n => n, n => n, (a, b) => `${a}-${b}`)
  .toArray();
// returns ['2-2', '3-3']

itiriri([{countryId: 1, code: '+1'}, {countryId: 2, code: '+44'}])
  .join(
    [{ id: 1, country: 'US' }, {id: 3, country: 'MD'}],
    left => left.countryId,
    right => right.id,
    (left, right) => ({country: right.country, code: left.code}))
  .toArray();
// returns [{country: 'US', code: '+1'}]
```
```

--------------------------------

### Convert sequence to array with `toArray`

Source: https://labs42io.github.io/itiriri

Creates an array from the sequence. An optional selector function can transform elements before inclusion in the array.

```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3]).toArray(); // returns [1, 2, 3]
itiriri([{value: 1}, {value: 2}]).toArray(elem => elem.value); // returns [1, 2]
```

--------------------------------

### Group elements by key with toGroups

Source: https://labs42io.github.io/itiriri

Use `toGroups` to create a Map where keys are derived from elements using `keySelector`. Optionally, transform values using `valueSelector`.

```javascript
import itiriri from 'itiriri';

itiriri([1, 7, 14, 4, 9]).toGroups(elem => elem % 2 === 0);
// returns Map {0 => [14, 4], 1 => [1, 7, 9]}
```

```javascript
import itiriri from 'itiriri';

itiriri([
    {name: 'Alice', gender: 'female'},
    {name: 'Bob', gender: 'male'},
    {name: 'David', gender: 'male'}
  ])
  .toGroups(elem => elem.gender, elem => elem.name);
// returns Map {'female' => ['Alice'], 'male' => ['Bob', 'David']}
```

--------------------------------

### takeWhile

Source: https://labs42io.github.io/itiriri

Returns elements from the sequence as long as they satisfy the provided predicate function.

```APIDOC
## `takeWhile`

Returns elements while they satisfy the predicate.

### Syntax
```
takeWhile<T>(predicate: (element: T, index: number) => boolean): IterableQuery<T>;
```

### Parameters
* `predicate` - _(required)_ function to test for each element, accepts two arguments:
  * `element` - the current element
  * `index` - the index of the current element

### Example
```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3]).takeWhile(() => true); // returns [1, 2, 3]
itiriri([1, 2, 3]).takeWhile(() => false); // returns []
itiriri([1, 2, 3]).takeWhile(e => e < 3); // returns [1, 2]
itiriri([1, 2, 3]).takeWhile(e => e % 2 === 0); // returns []
```

`takeWhile` _is a deferred method and is executed only when the result sequence is iterated._
```

--------------------------------

### values()

Source: https://labs42io.github.io/itiriri

Returns a sequence of values for each index in the source sequence. This is a deferred method and is executed only when the result sequence is iterated.

```APIDOC
## `values`

### Description
Returns a sequence of values for each index in the source sequence.

### Syntax
```typescript
values(): IterableQuery<T>;
```

### Deferred Execution
`values` is a deferred method and is executed only when the result sequence is iterated.

### Example
```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3]]).values().toArray(); // returns [1, 2, 3]
```
```

--------------------------------

### reverse

Source: https://labs42io.github.io/itiriri

Returns a new sequence with the elements in a reversed order. This is a deferred method.

```APIDOC
## reverse

### Description
Returns a sequence of elements in a reversed order.

### Syntax
```typescript
reverse(): IterableQuery<T>;
```

### Remarks
`reverse` is a deferred method and is executed only when the result sequence is iterated.

### Example
```typescript
import itiriri from 'itiriri';

itiriri([1, 2, 3]).reverse().toArray(); // returns [3, 2, 1]
```
```

--------------------------------

### shuffle

Source: https://labs42io.github.io/itiriri

Returns the sequence of elements in a random order. This method is implemented using the Fisher–Yates algorithm for generating random permutations, utilizing `Math.rand()` for random number generation.

```APIDOC
## `shuffle`

### Description
Returns the sequence of elements in a random order. This method is implemented using the Fisher–Yates algorithm for generating random permutations, utilizing `Math.rand()` for random number generation.

### Syntax
```typescript
shuffle(): IterableQuery<T>;
```

### Example
```typescript
import itiriri from 'itiriri';

itiriri([1, 2, 3, 4, 5]).shuffle().toArray();
// returns a random permutation of the same elements
// like: [2, 5, 3, 1, 4]
```
```

--------------------------------

### Group elements by key with groupBy

Source: https://labs42io.github.io/itiriri

Use `groupBy` to group elements based on a key extracted by the `keySelector` function. An optional `valueSelector` can transform the grouped values. This method is deferred and executed upon iteration.

```javascript
import itiriri from 'itiriri';

const students = [
  {name: 'Alice', gender: 'female'},
  {name: 'Bob', gender: 'male'},
  {name: 'David', gender: 'male'},
];

itiriri(students).groupBy(elem => elem.gender, elem => elem.name).toArray();
// [['female', ['Alice']], ['male', ['Bob', 'David']]]
```

--------------------------------

### Calculate sum of elements with `sum`

Source: https://labs42io.github.io/itiriri

Calculates the sum of all elements in a sequence. An optional selector function can transform elements before summing.

```javascript
import itiriri from 'itiriri';

itiriri([1, 2, 3]).sum(); // returns 6
itiriri([{value: 1}, {value: 2}]).sum(elem => elem.value); // returns 3
```

--------------------------------

### reduce

Source: https://labs42io.github.io/itiriri

Applies a function against an accumulator and each element from left to right to reduce the sequence to a single value. An optional initial value can be provided.

```APIDOC
## reduce

### Description
Applies a function against an accumulator and each element (from left to right) to reduce it to a single value.

### Syntax
```typescript
reduce(
    callback: (accumulator: T, current: T, index: number) => T,
  ): T;

reduce<S>(
    callback: (accumulator: S, current: T, index: number) => S,
    initialValue: S,
  ): S;
```

### Parameters
#### Path Parameters
- **callback** (function) - Required - function to execute on each element in the sequence, taking three arguments: `accumulator`, `current`, and `currentIndex`.
- **initialValue** (S) - Optional - value to use as the first argument to the first call of the `callback`.

### Remarks
Calling `reduce` on an empty sequence without an initial value throws an error.

### Example
```typescript
import itiriri from 'itiriri';

itiriri([ 1, 2, 42, 0 ]).reduce((acc, elem) => Math.max(acc, elem)); // returns 42
itiriri([ 1, 2, 3 ]).reduce((acc, elem) => acc + elem, 10); // returns 16
```
```

--------------------------------

### min

Source: https://labs42io.github.io/itiriri

Returns the minimum element in a sequence. An optional comparison function can be provided to define the ordering.

```APIDOC
## min

### Description
Returns the minimum element in a sequence. An optional comparison function can be provided to define the ordering. If the sequence is empty, returns `undefined`.

### Syntax
```typescript
min(): number;
min(compareFn: (a: T, b: T) => number): T;
```

### Parameters
* `compareFn` - _(optional)_ a comparer function that compares two elements from a sequence and returns: -1 when `a` is less than `b`, 1 when `a` is greater `b`, 0 when `a` equals to `b`.

### Example
```typescript
import itiriri from 'itiriri';

itiriri([1, 2, 3]).min(); // returns 1
itiriri([]).min(); // returns undefined
itiriri([7, 3, 11, 5]).min((a, b) => (1 / a) - (1 / b)); // returns 11
```
```

--------------------------------

### groupBy

Source: https://labs42io.github.io/itiriri

Groups elements by a given key, optionally applying a transformation over each element. This is a deferred method and is executed only when the result sequence is iterated.

```APIDOC
## groupBy<K>(keySelector: (element: T, index: number) => K): IterableQuery<[K, IterableQuery<T>]>;

## groupBy<K, E>(keySelector: (element: T, index: number) => K, valueSelector: (element: T, index: number) => E): IterableQuery<[K, IterableQuery<E>]>;

### Description
Groups elements by a given key, optionally applying a transformation over each element.

### Parameters
* `keySelector` - _(required)_ function that provides element’s group key, accepts two arguments:
  * `element` - the current element
  * `index` - the index of the current element
  * returns the group key of current element
* `valueSelector` - _(optional)_ function to transform values, accepts two arguments:
  * `element` - the current element
  * `index` - the index of the current element
  * returns a transformation of current element

### Example
```javascript
import itiriri from 'itiriri';

const students = [
  {name: 'Alice', gender: 'female'},
  {name: 'Bob', gender: 'male'},
  {name: 'David', gender: 'male'},
];

itiriri(students).groupBy(elem => elem.gender, elem => elem.name).toArray();
// [['female', ['Alice']], ['male', ['Bob', 'David']]]
```

`groupBy` _is a deferred method and is executed only when the result sequence is iterated._
```

--------------------------------

### rightJoin

Source: https://labs42io.github.io/itiriri

Returns a sequence of correlated elements transformation that match a given key. This method performs an SQL-like right join. When an element from the right sequence doesn't match any from the left, the left value is passed as undefined.

```APIDOC
## `rightJoin`

### Description
Returns a sequence of correlated elements transformation that match a given key. This method performs an SQL-like right join. When an element from the right sequence doesn't match any from the left, the left value is passed as undefined.

### Syntax
```typescript
rightJoin<TKey, TRight, TResult>(other: Iterable<TRight>, rightKeySelector: (element: TRight, index: number) => TKey, leftKeySelector: (element: T, index: number) => TKey, joinSelector: (right: TRight, left?: T) => TResult): IterableQuery<TResult>;
```

### Parameters
* `other` - _(required)_ sequence to join
* `rightKeySelector` - _(required)_ function that provides the key of each element from joined sequence, accepts two arguments: `element` (the current element), `index` (the index of the current element), and returns element’s key.
* `leftKeySelector` - _(required)_ function that provides the key of each element from source sequence, accepts two arguments: `element` (the current element), `index` (the index of the current element), and returns element’s key.
* `joinSelector` - _(required)_ a transformation function to apply on each matched tuple, accepts two arguments: `right` (element from the joined sequence), `left` (element from the source sequence, or `undefined` if no match found), and returns new result.

### Example
```typescript
import itiriri from 'itiriri';

itiriri([1, 2, 3])
  .rightJoin([2, 3, 4, 2], n => n, n => n, (a, b) => `${a || '#'}-${b}`)
  .toArray();
// returns ['2-2', '3-3', '#-4', '2-2']

itiriri([{book: 'History', owner: 3}, {book: 'Math', owner: 2}])
  .rightJoin(
    [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Eve'}],
    right => right.id,
    left => left.owner,
    (right, left) => ({student: right.name, book: left && left.book || '--'})
  )
  .toArray();
// returns [
//   {student: 'Alice', book: '--'},
//   {student: 'Bob', book: 'Math'},
//   {student: 'Eve', book: 'History'}]
```
```

--------------------------------

### toGroups

Source: https://labs42io.github.io/itiriri

Creates a map of element groups by a given key. The value can be an array of elements or transformed elements.

```APIDOC
## toGroups

### Description
Creates a map of element groups by a given key. The value can be an array of elements or transformed elements.

### Syntax
```javascript
toGroups<M>(keySelector: (element: T, index: number) => M): Map<M, T[]>;
toGroups<M, N>(keySelector: (element: T, index: number) => M, valueSelector: (element: T, index: number) => N): Map<M, N[]>;
```

### Parameters
* `keySelector` - _(required)_ A transformer function to apply to each element to get its key. Accepts two arguments: `element` (the current element) and `index` (the index of the current element).
* `valueSelector` - _(optional)_ A transformer function to apply to each element. Accepts two arguments: `element` (the current element) and `index` (the index of the current element).

### Example
```javascript
import itiriri from 'itiriri';

itiriri([1, 7, 14, 4, 9]).toGroups(elem => elem % 2 === 0);
// returns Map {0 => [14, 4], 1 => [1, 7, 9]}

itiriri([
    {name: 'Alice', gender: 'female'},
    {name: 'Bob', gender: 'male'},
    {name: 'David', gender: 'male'}
  ])
  .toGroups(elem => elem.gender, elem => elem.name);
// returns Map {'female' => ['Alice'], 'male' => ['Bob', 'David']}
```
```