ts-sparse-set/README.md

TS SparseSet

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

npm install ts-sparse-set

Usage Example

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.

---

Feel free to contribute, report issues, or suggest improvements on GitHub.