### Install and Test itiriri

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Install the itiriri package and run its test suite.

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

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

### Install itiriri

Source: https://context7.com/labs42io/itiriri/llms.txt

Install the itiriri library using npm.

```bash
npm install itiriri --save
```

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

### Working with Infinite Iterables: Fibonacci Example

Source: https://context7.com/labs42io/itiriri/llms.txt

Demonstrates how itiriri's deferred execution allows efficient processing of infinite sequences. Examples include finding specific numbers, summing, filtering, and grouping.

```typescript
import itiriri from 'itiriri';

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

// Get 42nd Fibonacci number
const f42 = itiriri(fibonacci()).nth(42);
console.log(f42); // 267914296

// Sum of first 10 Fibonacci numbers
const sumFirst10 = itiriri(fibonacci()).take(10).sum();
console.log(sumFirst10); // 88

// First 5 Fibonacci numbers containing '42'
const containing42 = itiriri(fibonacci())
  .filter(x => x.toString().includes('42'))
  .take(5);
console.log(containing42.toArray()); // [267914296, 4807526976, ...]

// Group first 100 by even/odd
const groups = itiriri(fibonacci())
  .take(100)
  .groupBy(x => x % 2 === 0 ? 'even' : 'odd')
  .map(([key, vals]) => `${key}: ${vals.length()}`);
console.log(groups.toArray()); // ['odd: 67', 'even: 33']
```

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

### Install itiriri via npm

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Command to add the library to your project dependencies.

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

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

### Take and Skip Elements

Source: https://context7.com/labs42io/itiriri/llms.txt

Utilize take() to get a specified number of elements from the start (or end with negative count) and skip() to discard elements from the start (or end with negative count). Both methods are deferred and work with infinite iterables. They can be combined for pagination.

```typescript
import itiriri from 'itiriri';

const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

// Take first 3 elements
console.log(itiriri(numbers).take(3).toArray()); // [1, 2, 3]

// Take last 3 elements (negative count)
console.log(itiriri(numbers).take(-3).toArray()); // [8, 9, 10]

// Skip first 7 elements
console.log(itiriri(numbers).skip(7).toArray()); // [8, 9, 10]

// Skip last 7 elements (negative count)
console.log(itiriri(numbers).skip(-7).toArray()); // [1, 2, 3]

// Combine take and skip for pagination
const page2 = itiriri(numbers).skip(3).take(3);
console.log(page2.toArray()); // [4, 5, 6]

// Works with infinite iterables
function* infinite() { let n = 1; while (true) yield n++; }
console.log(itiriri(infinite()).take(5).toArray()); // [1, 2, 3, 4, 5]
```

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

### Perform includes check

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Example usage of includes to verify if an element exists in a sequence.

```ts
import itiriri from 'itiriri';

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

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

### fill()

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Returns a sequence filled from a start index to an end index with a static value.

```APIDOC
## fill()

### Description
Returns a sequence filled from a start index to an end index with a static value. This is a deferred method.

### Parameters
- **value** (T) - Required - Value to fill
- **start** (number) - Optional - Start index, defaults to 0
- **end** (number) - Optional - End index, defaults to sequence length

### Request Example
```ts
itiriri([1, 2, 3, 4, 5]).fill([7]).toArray();
```
```

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

### Bundle itiriri for Browser Use

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Install dependencies and use the gulp bundle task to create a minified JavaScript file for browser inclusion.

```bash
$ npm install
$ gulp bundle
```

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

### Perform indexOf search

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Example usage of indexOf to find the index of elements in a sequence.

```ts
import itiriri from 'itiriri';

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

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

### Take a specified number of elements from the start

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Returns a new sequence containing the first `count` elements. If `count` is negative, elements are taken from the end. This method is deferred.

```typescript
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]
```

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

### Get First Element with first

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Returns the first element of a sequence or undefined if empty.

```ts
first(): T;
```

```ts
import itiriri from 'itiriri';

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

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

### Perform groupJoin operation

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Example usage of groupJoin to correlate categories with books.

```ts
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();
```

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

### Create Iterable Queries

Source: https://context7.com/labs42io/itiriri/llms.txt

Wrap arrays, Sets, Maps, or generators with itiriri() to create queryable iterables. Examples include summing array elements, converting a Set to an array, and taking elements from a generator.

```typescript
import itiriri from 'itiriri';

// From array
const fromArray = itiriri([1, 2, 3, 4, 5]);
console.log(fromArray.sum()); // 15

// From Set
const fromSet = itiriri(new Set(['a', 'b', 'c']));
console.log(fromSet.toArray()); // ['a', 'b', 'c']

// From generator function
function* numbers() {
  let n = 1;
  while (true) yield n++;
}
const fromGenerator = itiriri(numbers()).take(5);
console.log(fromGenerator.toArray()); // [1, 2, 3, 4, 5]
```

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

### Perform intersect operation

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Example usage of intersect with and without a selector function.

```ts
import itiriri from 'itiriri';

itiriri([1, 2, 3]]).intersect([2, 3, 4]).toArray(); // returns [2, 3]
itiriri([{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'})
  .intersect([{id: 3, name: 'David'}, {id: 1, name: 'Alice'}], elem => elem.id)
  .toArray(); // returns [{id: 1, name: 'Alice'}]
```

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

### Get entries from an iterable

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Returns a sequence of key/value pairs for each element and its index. This is a deferred method.

```ts
entries(): IterableQuery<[number, T]>;
```

```ts
import itiriri from 'itiriri';

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

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

### Use takeWhile and skipWhile

Source: https://context7.com/labs42io/itiriri/llms.txt

Use `takeWhile` to get elements as long as a condition is met, and `skipWhile` to discard elements until a condition is met. Both are deferred methods.

```typescript
import itiriri from 'itiriri';

const numbers = [1, 2, 3, 4, 5, 4, 3, 2, 1];

// Take while less than 4
console.log(itiriri(numbers).takeWhile(x => x < 4).toArray()); // [1, 2, 3]

// Skip while less than 4
console.log(itiriri(numbers).skipWhile(x => x < 4).toArray()); // [4, 5, 4, 3, 2, 1]

// Take while with index
const indexed = itiriri(['a', 'b', 'c', 'd']).takeWhile((_, idx) => idx < 2);
console.log(indexed.toArray()); // ['a', 'b']

// Empty result when first element fails predicate
console.log(itiriri([5, 1, 2]).takeWhile(x => x < 3).toArray()); // []
```

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

### take

Source: https://github.com/labs42io/itiriri/blob/master/README.md

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

```APIDOC
## take

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

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

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

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

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

### Request Example
```ts
import itiriri from 'itiriri';

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

### Response
#### Success Response (IterableQuery<T>)
Returns an `IterableQuery` object containing the specified number of elements.

#### Response Example
```json
[1, 2]
```
```

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

### prepend Method

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Adds elements to the beginning of a sequence.

```APIDOC
## prepend(other: Iterable<T> | T)

### Description
Returns a sequence with given elements at the beginning. This is a deferred method.

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

### Response
- **IterableQuery<T>** - A new sequence with the prepended elements.
```

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

### forEach

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Runs through every element and applies a given function.

```APIDOC
## forEach

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

### Parameters
- **action** (function) - Required - Function to apply on each element, accepts (element, index).
```

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

### first

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Returns the first element in a sequence.

```APIDOC
## first

### Description
Returns the first element in a sequence. For an empty sequence returns undefined.
```

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

### Join Method

Source: https://github.com/labs42io/itiriri/blob/master/README.md

The `join` method performs an SQL-like inner join on two sequences based on specified key selectors and returns a transformed sequence of the joined elements. It is a deferred method.

```APIDOC
## join

### Description
Returns a sequence of correlated elements transformation that match a given key. Works as an SQL inner join.

### Method
`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
#### Parameters
- **other** (Iterable<TRight>) - Required - Sequence to join.
- **leftKeySelector** ((element: T, index: number) => TKey) - Required - Function that provides the key of each element from the source sequence.
  - `element` (T) - The current element.
  - `index` (number) - The index of the current element.
  - returns element's key.
- **rightKeySelector** ((element: TRight, index: number) => TKey) - Required - Function that provides the key of each element from the joined sequence.
  - `element` (TRight) - The current element.
  - `index` (number) - The index of the current element.
  - returns element's key.
- **joinSelector** ((left: T, right: TRight) => TResult) - Required - A transformation function to apply on each matched tuple.
  - `left` (T) - Element from the source sequence.
  - `right` (TRight) - Element from the joined sequence.
  - returns a new result.

### Request 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'}]
```

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

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

### reverse Method

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Returns a sequence of elements in reversed order.

```APIDOC
## reverse()

### Description
Returns a sequence of elements in a reversed order. This is a deferred method.

### Response
- **IterableQuery<T>** - The reversed sequence.
```

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

### Skip Elements in Sequence

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Skips a specified number of elements from the start, or from the end if the count is negative.

```ts
skip(count: number): IterableQuery<T>;
```

```ts
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]
```

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

### Get last element with last

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Returns the final element of a sequence, or undefined if the sequence is empty.

```ts
last(): T;
```

```ts
import itiriri from 'itiriri';

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

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

### Prepend elements to a sequence

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Adds elements or another sequence to the beginning of the current sequence. This is a deferred method.

```ts
prepend(other: Iterable<T>): IterableQuery<T>;
prepend(other: T): IterableQuery<T>;
```

```ts
import itiriri from 'itiriri';

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

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

### Slice Sequence Range

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Extracts a range of elements from the sequence based on start and optional end indices.

```ts
slice(start: number): IterableQuery<T>;
slice(start: number, end: number): IterableQuery<T>;
```

```ts
import itiriri from 'itiriri';

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

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

### Counting Elements with itiriri length

Source: https://context7.com/labs42io/itiriri/llms.txt

Get the total number of elements in a sequence or count elements that satisfy a given predicate.

```typescript
import itiriri from 'itiriri';

const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

// Total count
console.log(itiriri(numbers).length()); // 10

// Count with predicate
console.log(itiriri(numbers).length(x => x > 5)); // 5

// Count even numbers
console.log(itiriri(numbers).length(x => x % 2 === 0)); // 5
```

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

### slice

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Extracts a portion of a sequence, returning a new sequence that represents the range of elements from a start index up to (but not including) an end index.

```APIDOC
## slice

### Description
Returns a sequence that represents the range of elements from start to end.

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

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `start` - *(required)* zero-based index at which to begin extraction.
* `end` - *(optional)* zero-based index before which to end extraction. The `end` index is not included in the result.

### Request Example
```ts
import itiriri from 'itiriri';

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

### Response
#### Success Response (200)
Returns an `IterableQuery<T>` representing the specified range of elements.

#### Response Example
(See Request Example for output structure)
```

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

### Use itiriri in Browser

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Include the bundled itiriri.min.js file in your HTML and use the itiriri function with an array or any Iterable.

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

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

### entries()

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Returns a sequence of key/value pairs for each element and its index.

```APIDOC
## entries()

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

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

### Request Example
```ts
itiriri(['Alice', 'Bob', 'David']).entries().toArray();
```

### Response
- **Result** (Array) - Returns [[0, 'Alice'], [1, 'Bob'], [2, 'David']]
```

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

### Sequence Filling: fill

Source: https://context7.com/labs42io/itiriri/llms.txt

Create a sequence where elements are replaced by a static value. Supports specifying start and end indices for the fill operation.

```typescript
import itiriri from 'itiriri';

const arr = [1, 2, 3, 4, 5];

// Fill entire sequence
console.log(itiriri(arr).fill(0).toArray()); // [0, 0, 0, 0, 0]

// Fill from index 2 to end
console.log(itiriri(arr).fill(0, 2).toArray()); // [1, 2, 0, 0, 0]

// Fill from index 1 to 3 (exclusive)
console.log(itiriri(arr).fill(0, 1, 3).toArray()); // [1, 0, 0, 4, 5]
```

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

### Get Sequence Values

Source: https://github.com/labs42io/itiriri/blob/master/README.md

The values method returns a sequence of values from the source sequence. This is a deferred method, executed only when the result sequence is iterated.

```typescript
import itiriri from 'itiriri';

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

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

### Iterate with forEach

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Applies a function to every element in the sequence.

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

```ts
import itiriri from 'itiriri';

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

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

### Get element at index with nth

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Retrieves an element at a specific index. Supports negative indices for reverse lookup and returns undefined if out of range.

```ts
nth(index: number): T;
```

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

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

### nth Method

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Retrieves the element at a specified index from the sequence.

```APIDOC
## nth(index: number)

### Description
Returns the element at a specified index. For a negative index, it returns the element from the end of the sequence. If the index is out of range, it returns undefined.

### Parameters
#### Path Parameters
- **index** (number) - Required - Zero-based index at which to get the element.

### Response
- **T** - The element at the specified index or undefined.
```

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

### Get Unique Elements

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Returns a sequence containing only unique elements. An optional selector function can specify the value to use for uniqueness comparison. This is a deferred method.

```typescript
import itiriri from 'itiriri';

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

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

### values Method

Source: https://github.com/labs42io/itiriri/blob/master/README.md

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

```APIDOC
## values

### Description
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.

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

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

### Import itiriri

Source: https://context7.com/labs42io/itiriri/llms.txt

Import the itiriri library into your TypeScript project.

```typescript
import itiriri from 'itiriri';
```

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

### Find first or last matching element

Source: https://context7.com/labs42io/itiriri/llms.txt

Use `find` to get the first element that satisfies a predicate, and `findLast` for the last. Returns undefined if no element matches.

```typescript
import itiriri from 'itiriri';

const users = [
  { name: 'Alice', role: 'admin' },
  { name: 'Bob', role: 'user' },
  { name: 'Charlie', role: 'admin' },
  { name: 'David', role: 'user' }
];

// Find first admin
const firstAdmin = itiriri(users).find(u => u.role === 'admin');
console.log(firstAdmin); // { name: 'Alice', role: 'admin' }

// Find last admin
const lastAdmin = itiriri(users).findLast(u => u.role === 'admin');
console.log(lastAdmin); // { name: 'Charlie', role: 'admin' }

// Find with index
const atIndex = itiriri([10, 20, 30, 40]).find((elem, idx) => idx === 2);
console.log(atIndex); // 30

// Returns undefined if not found
console.log(itiriri(users).find(u => u.role === 'guest')); // undefined
```

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

### Keys Method

Source: https://github.com/labs42io/itiriri/blob/master/README.md

The `keys` method returns a sequence of numerical indices corresponding to 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.

### Method
`keys(): IterableQuery<number>;`

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

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

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

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

### flat

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Returns a sequence with all sub-sequences concatenated.

```APIDOC
## flat

### Description
Returns a sequence with all sub-sequences concatenated. This is a deferred method.

### Parameters
- **selector** (function) - Required - A transformation function to map each element to a sequence, accepts (element, index) and returns an iterable.
```

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

### Modify sequence by adding/removing elements

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Splices elements into or out of the sequence. Specify the starting index, the number of elements to delete, and optionally, new elements to insert. This method is deferred.

```typescript
import itiriri from 'itiriri';

itiriri(['angel', 'clown', 'mandarin', 'sturgeon'])
  .splice(2, 0, 'drum').toArray();
// returns ['angel', 'clown', 'drum', 'mandarin', 'sturgeon']

itiriri(['angel', 'clown', 'drum', 'mandarin', 'sturgeon'])
  .splice(3, 1).toArray();
// returns ['angel', 'clown', 'drum', 'sturgeon']
```

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

### Getting Unique Elements with itiriri distinct

Source: https://context7.com/labs42io/itiriri/llms.txt

Extract unique elements from a sequence. Optionally provide a selector function to determine uniqueness based on a computed value or property.

```typescript
import itiriri from 'itiriri';

// Remove duplicates from primitives
const numbers = [1, 2, 2, 3, 3, 3, 4];
console.log(itiriri(numbers).distinct().toArray()); // [1, 2, 3, 4]

// Distinct with selector
const users = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
  { id: 1, name: 'Alice Clone' }
];

const uniqueById = itiriri(users).distinct(u => u.id);
console.log(uniqueById.toArray());
// [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]

// Distinct by computed value
const words = ['apple', 'APPLE', 'Apple', 'banana'];
const uniqueWords = itiriri(words).distinct(w => w.toLowerCase());
console.log(uniqueWords.toArray()); // ['apple', 'banana']
```

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

### find()

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Finds the first element that satisfies the specified predicate.

```APIDOC
## find()

### Description
Finds the first element that satisfies the specified predicate. Returns undefined if not found.

### Parameters
- **predicate** (function) - Required - Function to test for each element (element, index) => boolean

### Request Example
```ts
itiriri([1, 2, 3, 4, 5]).find(elem => elem % 2 === 0);
```
```

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

### toMap

Source: https://github.com/labs42io/itiriri/blob/master/README.md

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

```APIDOC
## toMap

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

### Method
`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
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request 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
```

### Response
#### Success Response (200)
`Map<M, T>` or `Map<M, N>`: A JavaScript Map where keys are derived from `keySelector` and values are the corresponding elements (or transformed elements).
```

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

### Find first or last index of element

Source: https://context7.com/labs42io/itiriri/llms.txt

Use `findIndex` to get the index of the first element satisfying a predicate, and `findLastIndex` for the last. Returns -1 if no element matches.

```typescript
import itiriri from 'itiriri';

const numbers = [1, 2, 3, 4, 5, 4, 3, 2, 1];

// Find first index where element > 3
console.log(itiriri(numbers).findIndex(x => x > 3)); // 3

// Find last index where element > 3
console.log(itiriri(numbers).findLastIndex(x => x > 3)); // 5

// Returns -1 when not found
console.log(itiriri(numbers).findIndex(x => x > 10)); // -1
```

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

### LastIndexOf Method

Source: https://github.com/labs42io/itiriri/blob/master/README.md

The `lastIndexOf` method finds the last index of a specified element within a sequence, optionally starting the search from a given index. It returns -1 if the element is not found.

```APIDOC
## lastIndexOf

### Description
Returns the last index at which a given element can be found.

### Method
`lastIndexOf(element: T): number;
lastIndexOf(element: T, fromIndex: number): number;`

### Parameters
#### Parameters
- **element** (T) - Required - The element to search for.
- **fromIndex** (number) - Optional - Starting index, defaults to `0`.

When an element is not found, returns `-1`. `lastIndexOf` uses triple equals `===` to compare elements.

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

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

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

### toSet

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Creates a set of elements from the sequence, optionally transforming elements before adding them to the set.

```APIDOC
## toSet

### Description
Creates a set of elements from the sequence, optionally transforming elements before adding them to the set.

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

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request 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}
```

### Response
#### Success Response (200)
`Set<T>` or `Set<S>`: A JavaScript Set containing the unique elements from the sequence.
```

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

### Find index of element

Source: https://context7.com/labs42io/itiriri/llms.txt

Use `indexOf` to find the first index of a specific element, and `lastIndexOf` for the last. Both support an optional `fromIndex` to start the search. Returns -1 if the element is not found.

```typescript
import itiriri from 'itiriri';

const items = ['a', 'b', 'c', 'b', 'a'];

// Find first occurrence
console.log(itiriri(items).indexOf('b')); // 1

// Find last occurrence
console.log(itiriri(items).lastIndexOf('b')); // 3

// Search from index
console.log(itiriri(items).indexOf('b', 2)); // 3

// Returns -1 when not found
console.log(itiriri(items).indexOf('z')); // -1
```

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

### Process infinite sequences with deferred execution

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Uses a generator to find values in an infinite Fibonacci sequence without buffering, demonstrating deferred execution.

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

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

### toString

Source: https://github.com/labs42io/itiriri/blob/master/README.md

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.

### Method
`toString(): string;`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request 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]
```

### Response
#### Success Response (200)
`string`: A comma-separated string of the elements in the sequence.
```

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

### Get first, last, or nth element

Source: https://context7.com/labs42io/itiriri/llms.txt

Retrieve the first, last, or an element at a specific index (including negative indexing) from a sequence. Returns undefined for out-of-range indices or empty sequences.

```typescript
import itiriri from 'itiriri';

const letters = ['a', 'b', 'c', 'd', 'e'];

// Get first element
console.log(itiriri(letters).first()); // 'a'

// Get last element
console.log(itiriri(letters).last()); // 'e'

// Get element at index 2
console.log(itiriri(letters).nth(2)); // 'c'

// Get element from end (negative index)
console.log(itiriri(letters).nth(-1)); // 'e'
console.log(itiriri(letters).nth(-2)); // 'd'

// Returns undefined for out of range
console.log(itiriri(letters).nth(100)); // undefined
console.log(itiriri([]).first()); // undefined
```

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

### Map elements to unique keys with toMap

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Creates a Map from a sequence. Throws an error if duplicate keys are encountered.

```ts
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>;
```

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

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

### Calculate Pi using a generator

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Demonstrates using a generator function with itiriri to perform map, take, and sum operations.

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

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

### Define includes syntax

Source: https://github.com/labs42io/itiriri/blob/master/README.md

The includes method signature for checking element existence.

```ts
includes(element: T): boolean;
includes(element: T, fromIndex: number): boolean;
```

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

### Find first matching element

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Returns the first element that satisfies the predicate, or undefined if none match.

```ts
find(predicate: (element: T, index: number) => boolean): T;
```

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

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

### union Method

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Returns a set union with a given sequence, optionally using a selector for comparisons.

```APIDOC
## union

### Description
Returns a set union with a given sequence. This is a deferred method and is executed only when the result sequence is iterated.

### Parameters
- **other** (Iterable<T>) - Required - The sequence to join with.
- **selector** ((element: T) => S) - Optional - A value transformer function to be used for comparisons.

### Request Example
```ts
itiriri([1, 2, 3]).union([2, 3, 4]).toArray(); // returns [1, 2, 3, 4]
```
```

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

### Join sequences with join

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Performs an SQL-style inner join on two sequences based on key selectors. The operation is deferred until the result is iterated.

```ts
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>;
```

```ts
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'}]
```

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

### Check conditions with every, some, includes

Source: https://context7.com/labs42io/itiriri/llms.txt

Use `every` to test if all elements satisfy a predicate, `some` to test if at least one does, and `includes` to check for the presence of a specific value. `includes` also supports an optional `fromIndex`.

```typescript
import itiriri from 'itiriri';

const numbers = [2, 4, 6, 8, 10];

// Check if all are even
console.log(itiriri(numbers).every(x => x % 2 === 0)); // true

// Check if any is greater than 5
console.log(itiriri(numbers).some(x => x > 5)); // true

// Check if sequence includes a value
console.log(itiriri(numbers).includes(6)); // true
console.log(itiriri(numbers).includes(7)); // false

// includes with fromIndex
console.log(itiriri(numbers).includes(2, 1)); // false (starts from index 1)

// every/some with index parameter
const indexed = itiriri(['a', 'b', 'c']);
console.log(indexed.every((elem, idx) => idx < 5)); // true
```

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

### Sequence Iteration: forEach

Source: https://context7.com/labs42io/itiriri/llms.txt

Execute a function for each element in the sequence. This method immediately iterates the sequence, unlike deferred methods.

```typescript
import itiriri from 'itiriri';

const items = ['apple', 'banana', 'cherry'];

// Simple iteration
itiriri(items).forEach(item => console.log(item));
// apple
// banana
// cherry

// With index
itiriri(items).forEach((item, idx) => {
  console.log(`${idx + 1}. ${item}`);
});
// 1. apple
// 2. banana
// 3. cherry

// Side effects
const results: string[] = [];
itiriri(items)
  .map(s => s.toUpperCase())
  .forEach(s => results.push(s));
console.log(results); // ['APPLE', 'BANANA', 'CHERRY']
```

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

### Retrieve sequence keys with keys

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Returns a sequence of indices for the source sequence. This is a deferred method.

```ts
keys(): IterableQuery<number>;
```

```ts
import itiriri from 'itiriri';

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

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

### Basic Aggregations with itiriri

Source: https://context7.com/labs42io/itiriri/llms.txt

Perform basic sum, average, min, and max aggregations on numeric sequences. For objects, use a selector function to specify the numeric property.

```typescript
import itiriri from 'itiriri';

const numbers = [1, 2, 3, 4, 5];

// Basic aggregations
console.log(itiriri(numbers).sum()); // 15
console.log(itiriri(numbers).average()); // 3
console.log(itiriri(numbers).min()); // 1
console.log(itiriri(numbers).max()); // 5

// With selector for objects
const products = [
  { name: 'Apple', price: 1.5 },
  { name: 'Banana', price: 0.75 },
  { name: 'Orange', price: 2.0 }
];

console.log(itiriri(products).sum(p => p.price)); // 4.25
console.log(itiriri(products).average(p => p.price)); // ~1.42

// min/max with custom comparator
const cheapest = itiriri(products).min((a, b) => a.price - b.price);
console.log(cheapest); // { name: 'Banana', price: 0.75 }

// Returns undefined for empty sequences
console.log(itiriri([]).sum()); // undefined
```

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

### toGroups

Source: https://github.com/labs42io/itiriri/blob/master/README.md

Creates a map of element groups by a given key. Elements can be grouped directly or transformed before grouping.

```APIDOC
## toGroups

### Description
Creates a map of element groups by a given key. Elements can be grouped directly or transformed before grouping.

### Method
`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
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request 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']}
```

### Response
#### Success Response (200)
`Map<M, T[]>` or `Map<M, N[]>`: A JavaScript Map where keys are derived from `keySelector` and values are arrays of elements (or transformed elements).
```