GuMap

A JavaScript Map wrapper with dot accessor notation and immutability features.

Installation

npm install @zachvictor/gu-map

Usage

import { createGuMap } from '@zachvictor/gu-map';

// Basic usage with dot notation
const map = createGuMap([['foo', 1], ['bar', 2]]);
console.log(map.foo);  // 1
map.baz = 3;           // set via dot notation
map.get('baz');        // 3 (standard Map methods work too)

// Iteration works as expected
for (const [key, value] of map) {
  console.log(key, value);
}

// Immutable properties (can add, cannot change)
const immutableProps = createGuMap([['x', 10]], {
  immutableProperties: true,
  throwErrorOnPropertyMutate: true
});
immutableProps.y = 20;  // OK: new property
immutableProps.x = 99;  // Error: cannot change existing property

// Fully immutable map
const frozen = createGuMap([['a', 1]], {
  immutableMap: true,
  throwErrorOnPropertyMutate: true
});
frozen.b = 2;  // Error: map is immutable

API

createGuMap(iterable?, options?)

Creates a new GuMap. Returns a Proxy wrapping a Map instance.

• iterable — Array or iterable of key-value pairs (same as Map)
• options — Configuration object (see below)

Returns a proxy that passes instanceof Map checks.

Configuration Options

Option	Type	Default	Description
immutableMap	boolean	false	Complete immutability—no add, change, or delete
immutableProperties	boolean	false	Properties can be added but not changed
throwErrorOnPropertyMutate	boolean	false	Throw error on mutation attempt (see note below)
throwErrorOnNonexistentProperty	boolean	false	Throw error when accessing nonexistent property

Note on throwErrorOnPropertyMutate: When false, mutation attempts are blocked but the behavior depends on JavaScript's strict mode. In ES modules (strict mode), blocked mutations throw TypeError. In non-strict mode, they fail silently.

Supported Map Methods

All standard Map methods work: get(), set(), has(), delete(), entries(), keys(), values(), forEach(), clear(), size, and Symbol.iterator.

Operators

• Dot notation: map.foo and map.foo = 1
• in operator: 'foo' in map
• Spread/iteration: [...map] and for...of
• delete operator: delete map.foo

Aliases

For backwards compatibility:

• GuMap is an alias for createGuMap
• GuMapConfig is an alias for normalizeConfig

Testing

npm test

Uses Node.js built-in test runner with 50 tests covering all configuration options and edge cases.

Why "GuMap"?

The name combines 固 (gù, meaning "solid" or "firm" in Chinese) with Map—a nod to the immutability features. Pronunciation: "goo-map".

License

MIT