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.`);
}

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

Node

npm install ubimap # or yarn add ubimap

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

Browser

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

const { UbiMap } = window.ubimap;

Url Import

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

1. Importing UbiMap

First, import the UbiMap class into your TypeScript file:

import { UbiMap } from 'ubimap';

2. Creating an Instance

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

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. Setting Key-Value Pairs

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

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:

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

4. Getting Values by Key

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

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

5. Getting Keys by Value

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

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

6. Listing Keys or Values with Prefixes

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

// 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']

7. Iterating Over Entries

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

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

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

Example

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:

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.