{"id":11265,"library":"map-or-similar","title":"Map Or Similar","description":"Map Or Similar is a JavaScript utility that provides a `Map`-like object, defaulting to the native `Map` if available in the environment, or falling back to a custom polyfill implementation otherwise. Currently at version 1.5.0, it focuses on delivering a high-performance, dependency-free solution for environments where native `Map` support might be lacking or incomplete. The library supports core `Map` methods such as `set`, `get`, `has`, `delete`, `forEach`, and the `size` property, making it suitable for basic key-value storage. It is designed to work seamlessly in both browser and Node.js environments. Its primary differentiator is its lightweight footprint and performance-oriented implementation, achieved by only replicating a subset of the full `Map` API, rather than attempting a complete polyfill.","status":"maintenance","version":"1.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/thinkloop/map-or-similar","tags":["javascript","map","polyfill","js","alternative","fast"],"install":[{"cmd":"npm install map-or-similar","lang":"bash","label":"npm"},{"cmd":"yarn add map-or-similar","lang":"bash","label":"yarn"},{"cmd":"pnpm add map-or-similar","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary usage pattern is CommonJS `require()`. While it might technically work with a default import in some bundlers, the package's design and documentation strongly suggest CJS.","wrong":"import MapOrSimilar from 'map-or-similar';","symbol":"MapOrSimilar","correct":"const MapOrSimilar = require('map-or-similar');"},{"note":"For ES Modules, assuming the CommonJS export (`module.exports = MapOrSimilar;`) maps to a default export in ESM environments. Named imports are not explicitly supported by the module's structure.","wrong":"import { MapOrSimilar } from 'map-or-similar';","symbol":"MapOrSimilar","correct":"import MapOrSimilar from 'map-or-similar';"},{"note":"The exported symbol is a constructor function and must be instantiated with `new` to create a map-like instance.","wrong":"const myMap = MapOrSimilar();","symbol":"Usage","correct":"const myMap = new MapOrSimilar();"}],"quickstart":{"code":"const MapOrSimilar = require('map-or-similar');\n\n// Create a new map-like object.\n// This will either be a native Map if available, or a custom polyfill implementation.\nconst myMap = new MapOrSimilar();\n\n// Set various types of keys and values\nmyMap.set('stringKey', 'stringValue');\nmyMap.set(123, { id: 1, name: 'Number Key Object' });\nconst complexKey = { type: 'object', id: 'complex' };\nmyMap.set(complexKey, 'value associated with complex object');\n\n// Retrieve values\nconsole.log('Value for stringKey:', myMap.get('stringKey'));\nconsole.log('Value for complexKey:', myMap.get(complexKey));\n\n// Check for existence and size\nconsole.log('Has 123?', myMap.has(123));\nconsole.log('Current size:', myMap.size);\n\n// Iterate over entries\nmyMap.forEach(function(value, key, map) {\n  console.log(`Key: ${JSON.stringify(key)}, Value: ${JSON.stringify(value)}`);\n});\n\n// Delete an entry\nmyMap.delete('stringKey');\nconsole.log('Size after deletion:', myMap.size);\nconsole.log('Has stringKey?', myMap.has('stringKey'));","lang":"javascript","description":"Demonstrates instantiation of `MapOrSimilar` and basic usage of its core methods: `set`, `get`, `has`, `size`, `forEach`, and `delete` with various key types."},"warnings":[{"fix":"Ensure your code only uses the explicitly supported methods: `set`, `get`, `has`, `delete`, `forEach`, and `size`. If full `Map` functionality is required, consider a comprehensive `Map` polyfill or target environments with native `Map` support.","message":"This library only implements a subset of the standard `Map` API. Methods like `keys()`, `values()`, `entries()`, `clear()`, and the `Symbol.iterator` are not supported. Attempting to use these will result in a `TypeError`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For Node.js, use `require('map-or-similar')`. For browser environments or projects using ESM, ensure your bundler (e.g., Webpack, Rollup, Parcel) is configured to correctly handle CJS modules imported into an ESM context.","message":"The library primarily targets CommonJS (CJS) environments as demonstrated by its `require()` examples. While modern bundlers might transpile ES Modules (ESM) `import` statements, direct ESM compatibility might vary or require specific build configurations.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If you specifically need to use the `map-or-similar` polyfill implementation even when native `Map` exists (e.g., for consistent behavior across environments or specific performance characteristics), you would need to manually check for and use its internal polyfill class if exposed, or use a different library that strictly enforces its own implementation.","message":"The package falls back to a polyfill only if `Map` is not available. In environments where `Map` *is* available but has specific quirks or performance issues you wish to avoid, this library will still return the native `Map` instance, not its own polyfill.","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":"Review the documentation and use only the supported methods: `set`, `get`, `has`, `delete`, `forEach`, and `size`. For iteration, rely on `forEach` instead of iterator methods.","cause":"Attempting to use a Map method (like `keys()`, `values()`, `entries()`, `clear()`) that is not implemented by `map-or-similar`.","error":"TypeError: myMap.keys is not a function"},{"fix":"Ensure you have `const MapOrSimilar = require('map-or-similar');` (CommonJS) or `import MapOrSimilar from 'map-or-similar';` (ESM, with bundler support) at the top of your file.","cause":"The `map-or-similar` module was not correctly imported or required, or the variable name `MapOrSimilar` was misspelled.","error":"ReferenceError: MapOrSimilar is not defined"}],"ecosystem":"npm"}