84 lines
2.5 KiB
Markdown
84 lines
2.5 KiB
Markdown
### TS SparseSet
|
|
|
|
[![NPM version][npm-image]][npm-url]
|
|
[![Downloads][downloads-image]][downloads-url]
|
|
|
|
**TS SparseSet** is a high-performance TypeScript data structure implementing a *sparse set*, enabling fast management of ID-based collections and ECS components.
|
|
|
|
#### Features
|
|
|
|
* **O(1) Operations:** `add`, `remove`, `get`, and `has` with dense storage.
|
|
* **Dense Storage:** Efficient memory layout for maximum performance and cache locality.
|
|
* **Swap-Remove:** Maintains a compact dense array after removals.
|
|
* **Reusable Structure:** Suitable for ECS components, entities, object pools, or other ID-based collections.
|
|
* **Optional Object Pool Integration:** Easy integration with object pools to minimize allocations.
|
|
* **TypeScript Native:** Fully typed and compatible with modern TypeScript.
|
|
|
|
#### Installation
|
|
|
|
```bash
|
|
npm install ts-sparse-set
|
|
```
|
|
|
|
#### Usage Example
|
|
|
|
```typescript
|
|
import { SparseSet } from 'ts-sparse-set';
|
|
|
|
// Create a new SparseSet for numbers
|
|
const set = new SparseSet<number>();
|
|
|
|
// Add elements
|
|
set.add(10, 42);
|
|
set.add(20, 100);
|
|
|
|
// Check existence
|
|
console.log(set.has(10)); // true
|
|
console.log(set.has(5)); // false
|
|
|
|
// Get element by ID
|
|
console.log(set.get(20)); // 100
|
|
|
|
// Overwrite existing value
|
|
set.add(10, 50);
|
|
console.log(set.get(10)); // 50
|
|
|
|
// Remove an element
|
|
set.remove(20);
|
|
console.log(set.has(20)); // false
|
|
|
|
// Add multiple elements and check dense array integrity
|
|
set.add(30, 300);
|
|
set.add(40, 400);
|
|
set.remove(10);
|
|
console.log(set.get(30)); // 300
|
|
console.log(set.get(40)); // 400
|
|
```
|
|
|
|
#### API Documentation
|
|
|
|
* **SparseSet Class**
|
|
|
|
* **Constructor:** `new SparseSet<V>()`
|
|
* **Methods:**
|
|
|
|
* `add(id: number, value: V): V` — adds a new element or updates an existing one.
|
|
* `get(id: number): V | null` — retrieves the element by ID or `null` if missing.
|
|
* `has(id: number): boolean` — checks if an element exists.
|
|
* `remove(id: number): void` — removes an element and keeps the dense array compact.
|
|
|
|
#### Note
|
|
|
|
SparseSet is ideal for ECS scenarios where entities and components are identified by numeric IDs. It is not a general-purpose Map/Set and is optimized for dense arrays and minimal operation cost.
|
|
|
|
Good luck!
|
|
|
|
---
|
|
|
|
Feel free to contribute, report issues, or suggest improvements on [GitHub](https://github.com/yazmeyaa/ts-sparse-set).
|
|
|
|
[npm-image]: https://img.shields.io/npm/v/ts-sparse-set.svg?style=flat-square
|
|
[npm-url]: https://npmjs.org/package/ts-sparse-set
|
|
[downloads-image]: https://img.shields.io/npm/dm/ts-sparse-set.svg?style=flat-square
|
|
[downloads-url]: https://npmjs.org/package/ts-sparse-set
|