@webeach/collection

🇺🇸 English version | 🇷🇺 Русская версия

Managed collection of items with hooks, events, and strict type safety.

📦 Installation

npm install @webeach/collection

or

pnpm install @webeach/collection

or

yarn add @webeach/collection

📥 Importing

ES Modules

import { Collection } from '@webeach/collection';

CommonJS

const { Collection } = require('@webeach/collection');

Browser

<script type="module">
  import { Collection } from 'https://unpkg.com/@webeach/collection'; 
</script>

🚀 Quick Start

Adding users

import { Collection } from '@webeach/collection';

const users = new Collection({
  primaryKey: 'id',
});

users.appendItem({
  id: 1,
  firstName: 'Ivan',
  lastName: 'Petrov',
});

users.appendItem({
  id: 2,
  firstName: 'Jason',
  lastName: 'Statham',
});

console.log(users.numItems); // 2
console.log(users.getItem(2).firstName); // Jason

Adding and replacing an item

import { Collection } from '@webeach/collection';

const products = new Collection({
  primaryKey: 'sku',
});

products.appendItem({ sku: 'A001', name: 'Laptop' });
products.replaceItem('A001', { sku: 'A001', name: 'Laptop Pro' });

console.log(products.getItem('A001')?.name); // 'Laptop Pro'

Bulk replacing items with setItems

import { Collection } from '@webeach/collection';

const tasks = new Collection({
  primaryKey: 'id',
  initialItems: [
    { id: 1, title: 'Initial Task 1' },
    { id: 2, title: 'Initial Task 2' },
  ],
});

// Completely replace the collection content
tasks.setItems([
  { id: 3, title: 'New Task 3' },
  { id: 4, title: 'New Task 4' },
]);

console.log(tasks.numItems); // 2
console.log(tasks.getItem(3)?.title); // 'New Task 3'

🛠 API

Collection

• constructor
• Methods
  • appendItem
  • addEventListener
  • appendItemAt
  • clear
  • dispatchEvent
  • forEach
  • getItem
  • hasItem
  • insertItemAfter
  • insertItemBefore
  • patchItem
  • removeEventListener
  • removeItem
  • replaceItem
  • reset
  • setItems
  • [Symbol.iterator]
• Properties
  • numItems
  • onUpdate
• Hooks
  • clear:*
  • insert:*
  • patch:*
  • remove:*

CollectionUpdateEvent

• constructor
• Inherits CustomEvent API

🔖 Releasing a new version

Releases are handled automatically using semantic-release.

Before publishing a new version, make sure:

• All changes are committed and pushed to the main branch.
• Commit messages follow the Conventional Commits format:
  • feat: ... — for new features
  • fix: ... — for bug fixes
  • chore: ..., refactor: ..., etc. — as needed
• Versioning is automatically determined based on commit types (patch, minor, major).

👨‍💻 Author

Development and maintenance: Ruslan Martynov

If you have suggestions or found a bug, feel free to open an issue or submit a pull request.

📄 License

This package is distributed under the MIT License.