flat-pair

A lightweight TypeScript library for storing key-value pairs using arrays. Provides serializable storage with efficient value-based lookups and zero-cost static methods.

For more awesome packages, check out my homepage💛

Features

• 🔍 Bidirectional Search: Find keys by values and values by keys
• 📦 Serializable: Easy JSON serialization/deserialization
• 🛡️ Type Safe: Full TypeScript support with generic types
• 🎯 Zero Cost: Static methods available for minimal overhead
• ⚡ Lightweight: No dependencies, minimal bundle size
• 🌲 Native Behavior: forEach, find acts like they are in Array. Equality check uses SameValueZero

Installation / Import

npm install flat-pair
# or
pnpm install flat-pair

import { FlatPair, FlatPairOperator, add, get, find ...others } from 'flat-pair';

Quick Start

FlatPair Class

FlatPair is a container class has an items array, it has methods that wrap the static functions for easier usage.

// userId - detail pair
const pairs = new FlatPair<number, Detail>();
pairs.add(1, { name: 'Alice', age: 30 }); // won't change value when key exists
pairs.set(2, { name: 'Bob', age: 25 });
pairs.remove(1);
pairs.find((value, key) => value.age > 20);

Using Static Functions (Zero Cost)

const items: any[] = [];

// Add items
add<string, string>(items, 'name', 'John');
add<string, number>(items, 'age', 12);

// Remove and other operations
remove(items, 'age'); // returns true
console.log(size(items)); // 1
clear(items); // empties the array

Using FlatPairOperator Class (For fixed type hint)

If you don't want to specify the generic types every time you call a static function, you can use FlatPairOperator which wraps the static functions with fixed generic types.

import { FlatPairOperator } from 'flat-pair';

const operator = new FlatPairOperator<string, number>();
const items: any[] = [];

operator.add(items, 'score', 100); // operator's add method is always typed
operator.add(items, 'level', 5);

console.log(operator.get(items, 'score')); // 100
console.log(operator.getByValue(items, 5)); // 'level'

Performance

FlatPair uses a simple array structure [key1, value1, key2, value2, ...] which provides:

• Memory Efficiency: No object overhead per pair
• Serialization: Direct JSON support
• Cache Friendly: Contiguous memory layout
• Predictable: O(n) operations with low constant factors

Note: For large datasets, consider using a Map or Object for O(1) lookups instead of this package.

License

MIT © Kasukabe Tsumugi