TypeScript Map Implementation

Common errors

• TypeError: TSMap is not a constructor

  cause Attempting to call `TSMap` directly without the `new` keyword, or incorrect CommonJS import.
  fix Ensure you are instantiating the class with `new TSMap()` and that your CommonJS import is `const TSMap = require('typescript-map').TSMap;`.

• Error: Cannot read properties of undefined (reading 'set')

  cause Trying to call methods on an uninitialized or incorrectly imported `TSMap` instance.
  fix Verify that `TSMap` has been correctly imported and instantiated (e.g., `const myMap = new TSMap();`).

• Argument of type 'TSMap<string, number>' is not assignable to parameter of type 'Map<string, number>'

  cause Passing a `TSMap` instance to a function or API that specifically expects a native `Map` object.
  fix This library is not a polyfill for the native `Map`. If native `Map` compatibility is required, consider using `es6-map` or adapting your code to accept `TSMap` where appropriate, or converting `TSMap` to a standard object if only basic iteration is needed.

Warnings

• gotcha This library is not an ES6 Map polyfill. It provides a similar interface but is a separate implementation. Do not expect it to patch `Map` or behave identically to the native `Map` specification in every edge case.
  Fix: If a full ES6 Map polyfill is required, use `es6-map` or a similar solution. This library is an alternative for specific use cases.
• gotcha Performance will degrade significantly for maps containing hundreds or thousands of keys, or when used in performance-critical code paths. The implementation does not use a hashing function to keep it small and simple.
  Fix: For large datasets or 'hot path' scenarios, use the native `Map` object or a robust polyfill/library that employs hashing (e.g., `es6-map`).
• gotcha When included directly in a browser via a `<script>` tag, the `TSMap` class is exposed as a global variable. This can lead to global namespace pollution or conflicts with other libraries.
  Fix: Prefer using module bundlers (like Webpack or Rollup) with ES modules or CommonJS imports to encapsulate the library's scope and avoid global variable conflicts.

Install

• npm install typescript-map npm
• yarn add typescript-map yarn
• pnpm add typescript-map pnpm

Imports

• TSMap
  wrong:

  import TSMap from 'typescript-map'

  correct:

  import { TSMap } from 'typescript-map'

  The primary class is a named export, not a default export. For TypeScript and modern JavaScript (ESM).
• TSMap
  wrong:

  const { TSMap } = require('typescript-map');

  correct:

  const TSMap = require('typescript-map').TSMap;

  For CommonJS environments, access the `TSMap` class from the module's property.
• TSMap

  <script src="tsmap.min.js"></script> // Then use global TSMap

  When used directly in a browser without a module loader, the library exposes `TSMap` as a global variable. Be mindful of global scope pollution.

Quickstart

Demonstrates basic instantiation, setting and getting values, type-safe usage with generics, initialization with an array, and a custom `fromJSON` method.

import { TSMap } from 'typescript-map';

// Basic usage, similar to native Map
const myMap = new TSMap();
myMap.set('foo', 'bar');
console.log(myMap.get('foo')); // Prints: bar

// With TypeScript generics for type safety
const typedMap = new TSMap<string, number>();
typedMap.set('apple', 1);
typedMap.set('banana', 2);
console.log(typedMap.get('apple')); // Prints: 1

// Initialize with an array of key-value pairs
const initMap = new TSMap<string, string>([
  ['key1', 'valueA'],
  ['key2', 'valueB']
]);
console.log(initMap.size); // Prints: 2

// Example of a custom function: fromJSON
const jsonMap = new TSMap().fromJSON({
    name: 'Alice',
    age: 30,
    city: 'New York'
}, false);
console.log(jsonMap.get('name')); // Prints: Alice