TypeScript Map Structure

1.0.3 · active · verified Sun Apr 19

ts-map is a TypeScript library that provides a Map-like data structure, mirroring the functionality of the native ES6 Map object but explicitly designed for TypeScript environments. Its current stable version is 1.0.3, with no specific release cadence indicated beyond that. The library aims to offer a familiar API for key-value pair storage, where keys can be of any type (including objects), not just strings, which is a key differentiator from plain JavaScript objects. It supports generics for strong typing of both keys and values, enhancing type safety in TypeScript projects. While it replicates standard Map methods like `set`, `get`, `has`, `delete`, `clear`, `size`, `keys`, `values`, `entries`, and `forEach`, its primary distinction lies in its explicit TypeScript typing and design, which might appeal to developers looking for a fully typed alternative. It's important to note that object keys are compared by reference, mirroring ES6 Map behavior, which is a common gotcha for developers expecting value-based comparison.

Common errors

```
Argument of type 'string' is not assignable to parameter of type 'Coder'.
```
cause Attempting to `set` a value that does not conform to the generic type `V` specified for the `TsMap` instance.

fix Ensure the value passed to the `set()` method matches the generic type `V` defined during `TsMap` instantiation (e.g., `new TsMap<number, Coder>()` requires `{ name: string }` objects for values).
```
ReferenceError: TsMap is not defined (or similar CommonJS error).
```
cause Attempting to import `ts-map` using CommonJS `require()` syntax in a module that expects ES module syntax, or in an environment where CommonJS is not correctly transpiled/loaded for this package.

fix Use the ES module import syntax: `import TsMap from 'ts-map';` to correctly import the `TsMap` class.

Warnings

gotcha When using objects or arrays as keys, `ts-map` (like native ES6 Map) compares them by reference, not by value. Different object instances, even if they have identical contents, will be treated as distinct keys.
Fix: Always use the exact same object or array instance when setting, getting, or deleting entries if you intend for them to be the same key. Avoid creating new instances (e.g., `map.get([1])` when `map.set([1], 'value')` was used with a different `[1]` array instance).
gotcha Omitting explicit generic type parameters during `TsMap` instantiation will result in the map's keys and values being implicitly typed as `any`, forfeiting TypeScript's type safety benefits.
Fix: Always explicitly define generic types for keys and values, for example, `new TsMap<KeyType, ValueType>()`, to ensure the compiler enforces type constraints on map operations.

Install

npm install ts-map npm
yarn add ts-map yarn
pnpm add ts-map pnpm

Imports

TsMap
wrong:
```
const TsMap = require('ts-map')
```
correct:
```
import TsMap from 'ts-map'
```
The library primarily uses a default export for the `TsMap` class. It ships with TypeScript types.
TsMap (Type Import)
```
import type TsMap from 'ts-map'
```
When only using TsMap as a type (e.g., for type annotations), use an explicit type import.
Constructor with generics
wrong:
```
const map = new TsMap()
```
correct:
```
const map = new TsMap<string, number>()
```
Always explicitly define generic types for keys and values to leverage full type safety; omitting them defaults to `any`.

Quickstart

Demonstrates basic instantiation, setting various key types, retrieving values, iterating over map entries, and using generics for type safety.

import TsMap from 'ts-map';

// Basic instantiation and usage
const map = new TsMap();
const k1: number = 1;
const k2: number[] = [2]; 
const k3: boolean = true;

map.set(1, "hello");
map.set(k2, "ts").set(k3, "map");

console.log('Get 1:', map.get(1));
console.log('Get k2:', map.get(k2));
console.log('Size:', map.size);
console.log('Keys:', map.keys());
console.log('Values:', map.values());

console.log('-- ForEach --');
map.forEach((value, key) => {
  console.log(key, ':', value);
});

// Constructor with parameter
const initialMap = new TsMap<number, string>([
  [1, "ok"],
  [2, "fail"]
]);
console.log('Initial map get 1:', initialMap.get(1));

// Class generic usage
interface Coder {
  name: string;
}

const typedMap = new TsMap<number, Coder>([
  [1, {name: 'lavyun'}]
]);

typedMap.set(2, {name: "tom"});
// typedMap.set(3, "jack"); // This line would cause a TypeScript error as expected
console.log('Typed map get 1:', typedMap.get(1));

view raw JSON →