# @telegram.ts/collection

[![NPM Version](https://img.shields.io/npm/v/@telegram.ts/collection)](https://www.npmjs.com/package/@telegram.ts/collection)
[![NPM Downloads](https://img.shields.io/npm/dt/@telegram.ts/collection.svg?maxAge=3600)](https://www.npmjs.com/package/@telegram.ts/collection)
[![License](https://img.shields.io/npm/l/@telegram.ts/collection)](https://github.com/telegramsjs/plugins/blob/main/LICENSE)

A powerful Map-based data structure with additional utility methods. This library extends JavaScript's native `Map` with methods inspired by Arrays, making it perfect for managing collections of data with unique identifiers.

## Features

- 🚀 **Extends Native Map** - Full compatibility with JavaScript's Map API
- 📦 **Rich Utility Methods** - 50+ methods for working with collections
- 🎯 **Type-Safe** - Written in TypeScript with full type inference
- ⚡ **Performance Optimized** - Caching and efficient iteration patterns
- 🔗 **Chainable API** - Fluent interface for method chaining
- 🛠️ **Array-like Methods** - Familiar methods like `filter`, `map`, `reduce`, and more

## Installation

```bash
npm install @telegram.ts/collection
```

```bash
yarn add @telegram.ts/collection
```

```bash
pnpm add @telegram.ts/collection
```

## Quick Start

```typescript
import { Collection } from "@telegram.ts/collection";

// Create a collection
const users = new Collection<string, User>();

// Add items
users.set("123", { id: "123", name: "Alice", age: 25 });
users.set("456", { id: "456", name: "Bob", age: 30 });

// Use utility methods
const adults = users.filter((user) => user.age >= 18);
const names = users.map((user) => user.name);
const oldest = users.reduce((prev, curr) =>
  curr.age > prev.age ? curr : prev,
);

// Chain operations
users
  .filter((user) => user.age > 20)
  .each((user) => console.log(user.name))
  .map((user) => user.age);
```

## Credits

This library is inspired by [`@discordjs/collection`](https://github.com/discordjs/discord.js/tree/main/packages/collection) and adapted for telegram.ts use cases.

## LICENSE

This project is licensed under the MIT License - see the [LICENSE](https://github.com/telegramsjs/collection/blob/main/LICENSE) file for details.

## Contributing

Contributions are welcome! If you find any issues or have suggestions for improvements, please create a `GitHub` issue or submit a pull request. Additionally, feel free to reach out to me on Telegram via my username `@SempaiJS` or on Discord using my username `sempaika_chess`.