{"id":12180,"library":"ts-map","title":"TypeScript Map Structure","description":"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.","status":"active","version":"1.0.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/lavyun/ts-map","tags":["javascript","typescript","Map","ts","ts-map"],"install":[{"cmd":"npm install ts-map","lang":"bash","label":"npm"},{"cmd":"yarn add ts-map","lang":"bash","label":"yarn"},{"cmd":"pnpm add ts-map","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses a default export for the `TsMap` class. It ships with TypeScript types.","wrong":"const TsMap = require('ts-map')","symbol":"TsMap","correct":"import TsMap from 'ts-map'"},{"note":"When only using TsMap as a type (e.g., for type annotations), use an explicit type import.","symbol":"TsMap (Type Import)","correct":"import type TsMap from 'ts-map'"},{"note":"Always explicitly define generic types for keys and values to leverage full type safety; omitting them defaults to `any`.","wrong":"const map = new TsMap()","symbol":"Constructor with generics","correct":"const map = new TsMap<string, number>()"}],"quickstart":{"code":"import TsMap from 'ts-map';\n\n// Basic instantiation and usage\nconst map = new TsMap();\nconst k1: number = 1;\nconst k2: number[] = [2]; \nconst k3: boolean = true;\n\nmap.set(1, \"hello\");\nmap.set(k2, \"ts\").set(k3, \"map\");\n\nconsole.log('Get 1:', map.get(1));\nconsole.log('Get k2:', map.get(k2));\nconsole.log('Size:', map.size);\nconsole.log('Keys:', map.keys());\nconsole.log('Values:', map.values());\n\nconsole.log('-- ForEach --');\nmap.forEach((value, key) => {\n  console.log(key, ':', value);\n});\n\n// Constructor with parameter\nconst initialMap = new TsMap<number, string>([\n  [1, \"ok\"],\n  [2, \"fail\"]\n]);\nconsole.log('Initial map get 1:', initialMap.get(1));\n\n// Class generic usage\ninterface Coder {\n  name: string;\n}\n\nconst typedMap = new TsMap<number, Coder>([\n  [1, {name: 'lavyun'}]\n]);\n\ntypedMap.set(2, {name: \"tom\"});\n// typedMap.set(3, \"jack\"); // This line would cause a TypeScript error as expected\nconsole.log('Typed map get 1:', typedMap.get(1));","lang":"typescript","description":"Demonstrates basic instantiation, setting various key types, retrieving values, iterating over map entries, and using generics for type safety."},"warnings":[{"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).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"Attempting to `set` a value that does not conform to the generic type `V` specified for the `TsMap` instance.","error":"Argument of type 'string' is not assignable to parameter of type 'Coder'."},{"fix":"Use the ES module import syntax: `import TsMap from 'ts-map';` to correctly import the `TsMap` class.","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.","error":"ReferenceError: TsMap is not defined (or similar CommonJS error)."}],"ecosystem":"npm"}