Map Or Similar

Common errors

• TypeError: myMap.keys is not a function

  cause Attempting to use a Map method (like `keys()`, `values()`, `entries()`, `clear()`) that is not implemented by `map-or-similar`.
  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.

• ReferenceError: MapOrSimilar is not defined

  cause The `map-or-similar` module was not correctly imported or required, or the variable name `MapOrSimilar` was misspelled.
  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.

Warnings

• gotcha 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`.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install map-or-similar npm
• yarn add map-or-similar yarn
• pnpm add map-or-similar pnpm

Imports

• MapOrSimilar
  wrong:

  import MapOrSimilar from 'map-or-similar';

  correct:

  const MapOrSimilar = require('map-or-similar');

  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.
• MapOrSimilar
  wrong:

  import { MapOrSimilar } from 'map-or-similar';

  correct:

  import MapOrSimilar from 'map-or-similar';

  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.
• Usage
  wrong:

  const myMap = MapOrSimilar();

  correct:

  const myMap = new MapOrSimilar();

  The exported symbol is a constructor function and must be instantiated with `new` to create a map-like instance.

Quickstart

Demonstrates instantiation of `MapOrSimilar` and basic usage of its core methods: `set`, `get`, `has`, `size`, `forEach`, and `delete` with various key types.

const MapOrSimilar = require('map-or-similar');

// Create a new map-like object.
// This will either be a native Map if available, or a custom polyfill implementation.
const myMap = new MapOrSimilar();

// Set various types of keys and values
myMap.set('stringKey', 'stringValue');
myMap.set(123, { id: 1, name: 'Number Key Object' });
const complexKey = { type: 'object', id: 'complex' };
myMap.set(complexKey, 'value associated with complex object');

// Retrieve values
console.log('Value for stringKey:', myMap.get('stringKey'));
console.log('Value for complexKey:', myMap.get(complexKey));

// Check for existence and size
console.log('Has 123?', myMap.has(123));
console.log('Current size:', myMap.size);

// Iterate over entries
myMap.forEach(function(value, key, map) {
  console.log(`Key: ${JSON.stringify(key)}, Value: ${JSON.stringify(value)}`);
});

// Delete an entry
myMap.delete('stringKey');
console.log('Size after deletion:', myMap.size);
console.log('Has stringKey?', myMap.has('stringKey'));