# @zachvictor/gu-map

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

Latest version **1.2.0** (published 2026-01-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install @zachvictor/gu-map
pnpm add @zachvictor/gu-map
yarn add @zachvictor/gu-map
bun add @zachvictor/gu-map
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2026-01-04 |
| First published | 2021-09-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 11.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | zmvictor |
| Maintainers | zmvictor |
| Keywords | ES6, ESNext, Map, immutable, dot, dotaccessor, dotaccessornotation, Proxy |

## Links

- npm: https://www.npmjs.com/package/@zachvictor/gu-map
- Repository: https://github.com/zachvictor/gu-map
- Homepage: https://github.com/zachvictor/gu-map#readme
- Issues: https://github.com/zachvictor/gu-map/issues
- npm.io page: https://npm.io/package/@zachvictor/gu-map

## Alternatives

- [@lexical/table](https://npm.io/package/@lexical/table.md) — 3.0M weekly downloads
- [mantine-datatable](https://npm.io/package/mantine-datatable.md) — 98.2K weekly downloads
- [react-native-collapsible-tab-view](https://npm.io/package/react-native-collapsible-tab-view.md) — 70.6K weekly downloads
- [@handsontable/vue3](https://npm.io/package/@handsontable/vue3.md) — 16.1K weekly downloads
- [vuewordcloud](https://npm.io/package/vuewordcloud.md) — 7.2K weekly downloads

## Recent versions

- 1.2.0 (latest) — 2026-01-04
- 1.1.3 — 2021-09-24
- 1.1.2 — 2021-09-24
- 1.1.1 — 2021-09-24
- 1.1.0 — 2021-09-24

## README

# GuMap

[![npm version](https://img.shields.io/npm/v/@zachvictor/gu-map.svg)](https://www.npmjs.com/package/@zachvictor/gu-map)
[![license](https://img.shields.io/npm/l/@zachvictor/gu-map.svg)](LICENSE)

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

## Installation

```bash
npm install @zachvictor/gu-map
```

## Usage

```javascript
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

```bash
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](LICENSE)

---
_Source: https://npm.io/package/@zachvictor/gu-map · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._