ubimap



``ts
type Team = 'Red' | 'Blue';
type Role = 'Attack' | 'Defense';

const match = new UbiMap<[Team, Role]>();

// unique keys and values!
match.set('Red', 'Attack', users[0]!.id);
match.set('Red', 'Defense', users[1]!.id);
match.set('Blue', 'Attack', users[2]!.id);
match.set('Blue', 'Defense', users[3]!.id);

const [team, role] = match.getKey(users[2]!.id)!;

console.log(team, role); // Blue Attack

const blueDefense = match.get('Blue', 'Defense');
const redDefense = match.get('Red', 'Defense');

for (const [team, role, userId] of match) {
console.log(${userId} has the role of ${role} in the ${team} team.);
}

for (const [, role, userId] of match.filter('Red')) {
console.log(${userId} has the role of ${role} in the Red team.);
}
`


Ubimap is a safe, typed, enumerable bidirectional map that ensures unique values and supports compound keys.






Table of Contents

- Table of Contents
- Installing
- Node
- Browser
- Url Import
- Getting Started with UbiMap
- Basic Usage
- 1. Importing UbiMap
- 2. Creating an Instance
- 3. Setting Key-Value Pairs
- 4. Getting Values by Key
- 5. Getting Keys by Value
- 6. Listing Keys or Values with Prefixes
- 7. Iterating Over Entries
- Example
- Error Handling
- License

Installing

$3

`sh
npm install ubimap # or yarn add ubimap
`

`js
const { UbiMap } = require('ubimap');
import { UbiMap } from 'ubimap';
`

$3

`html
crossorigin
src="https://cdn.jsdelivr.net/npm/ubimap@latest/dist/index.umd.js"
>
`

`js
const { UbiMap } = window.ubimap;
`

$3

`ts
import { UbiMap } from 'https://cdn.skypack.dev/ubimap@latest';
`

Getting Started with UbiMap

UbiMap is a safe, bidirectional map that allows you to store and retrieve values based
on compound keys. It ensures that both keys and values are unique and provides methods to
query the map in both directions. This guide will walk you through how to set up and use
UbiMap.

Basic Usage

$3

First, import the UbiMap class into your TypeScript file:

`ts
import { UbiMap } from 'ubimap';
`

$3

To create an instance of UbiMap, simply pass the key structure as a tuple type, and
optionally, the value type and separator:

`ts
const ubimap = new UbiMap<[string, string]>();
`

- K is the tuple representing the compound key.
- V is the type of the values (default is string).
- S is the separator used to join the key components (default is ' ').

$3

You can set key-value pairs using the set method:

`ts
ubimap.set('a', 'b', 'value1'); // Key: 'a b', Value: 'value1'
ubimap.set('c', 'd', 'value2'); // Key: 'c d', Value: 'value2'
`

Both keys and values must be unique. If you try to add a duplicate key or value, an error
will be thrown:

`ts
ubimap.set('a', 'b', 'value1'); // This will throw an error if 'a b' already exists.
`

$3

You can retrieve values by using the get method, providing the components of the key as
separate arguments:

`ts
const value = ubimap.get('a', 'b'); // Returns 'value1'
`

$3

If you want to find the key associated with a value, you can use the getKey method:

`ts
const key = ubimap.getKey('value1'); // Returns 'a b'
`

$3

You can list keys or values that match a given prefix using keys and values:

`ts
// List keys with a prefix 'a'
const keysWithPrefix = ubimap.keys('a'); // ['a b']

// List values with a prefix 'value'
const valuesWithPrefix = ubimap.values('value'); // ['value1', 'value2']
`

$3

You can also iterate over all key-value pairs using a for...of loop:

`ts
for (const [firstKey, secondKey, value] of ubimap) {
console.log(firstKey, secondKey, value);
}
`

This will log each key-value pair in the map.

Example

`ts
import { UbiMap } from 'ubimap';

// Create a new UbiMap with compound keys and string values
const ubimap = new UbiMap<[string, string]>();

// Add some key-value pairs
ubimap.set('a', 'b', 'value1');
ubimap.set('c', 'd', 'value2');

// Retrieve a value by key
const value = ubimap.get('a', 'b'); // 'value1'

// Retrieve the key for a value
const key = ubimap.getKey('value2'); // 'c d'

// List all keys with the prefix 'a'
const keysWithPrefix = ubimap.keys('a'); // ['a b']

// Iterate through all entries
for (const [key, value] of ubimap) {
console.log(key, value);
}
`

Error Handling

If you try to add a duplicate key or value, an error can be thrown. For example:

`ts
try {
ubimap.set('a', 'b', 'value1');
ubimap.set('a', 'b', 'value2');
} catch (error) {
if (error instanceof KeyAlreadyExistsError) {
console.error(error.message);
}

if (error instanceof ValueAlreadyExistsError) {
console.error(error.message);
}
}
`

License

Licensed under the MIT. See LICENSE` for more informations.