# useMap

> Manage a Map as immutable React state.

- Category: State
- Package: `hookli` (install with `npm i hookli`)
- Docs: https://hookli.vercel.app/docs/use-map

## Signature

```ts
useMap<K, V>(initialState?: MapOrEntries<K, V>): [ReadOnlyMap<K, V>, UseMapActions<K, V>]
```

## Parameters

- `initialState`: `MapOrEntries<K, V>` (default: `new Map()`) — Initial entries as a Map or an array of [key, value] pairs.

## Returns

- `[0] map`: `ReadOnlyMap<K, V>` — A read-only view of the map — the mutating set/clear/delete methods are omitted; use the actions instead. get, has, size and iteration remain.
- `[1] actions`: `UseMapActions<K, V>` — Stable helpers that replace the map with a fresh copy so React re-renders — see below.

## Types

### UseMapActions

The second tuple element — the map mutation helpers.

- `set`: `(key: K, value: V) => void` — Adds or updates one entry.
- `setAll`: `(entries: MapOrEntries<K, V>) => void` — Replaces every entry with the given Map or [key, value] pairs.
- `remove`: `(key: K) => void` — Deletes the entry for the given key.
- `reset`: `() => void` — Empties the map.

## Usage

```tsx
import { useMap } from "hookli";

export function Demo() {
  const [map, { set, remove, reset }] = useMap<string, string>([
    ["theme", "dark"],
  ]);

  return (
    <div>
      <button onClick={() => set("lang", "en")}>Set lang</button>
      <button onClick={() => remove("theme")}>Remove theme</button>
      <button onClick={reset}>Reset</button>
      <ul>
        {[...map.entries()].map(([key, value]) => (
          <li key={key}>{key}: {value}</li>
        ))}
      </ul>
    </div>
  );
}
```

## Source

`src/hooks/use-map/use-map.ts`

```ts
import { useCallback, useState } from "react";

export type MapOrEntries<K, V> = Map<K, V> | [K, V][];

export interface UseMapActions<K, V> {
  set: (key: K, value: V) => void;
  setAll: (entries: MapOrEntries<K, V>) => void;
  remove: (key: K) => void;
  reset: () => void;
}

export type ReadOnlyMap<K, V> = Omit<Map<K, V>, "set" | "clear" | "delete">;

export type UseMapReturn<K, V> = [ReadOnlyMap<K, V>, UseMapActions<K, V>];

export function useMap<K, V>(
  initialState: MapOrEntries<K, V> = new Map(),
): UseMapReturn<K, V> {
  const [map, setMap] = useState(() => new Map(initialState));

  const set = useCallback((key: K, value: V) => {
    setMap((prev) => {
      const next = new Map(prev);
      next.set(key, value);
      return next;
    });
  }, []);

  const setAll = useCallback((entries: MapOrEntries<K, V>) => {
    setMap(new Map(entries));
  }, []);

  const remove = useCallback((key: K) => {
    setMap((prev) => {
      const next = new Map(prev);
      next.delete(key);
      return next;
    });
  }, []);

  const reset = useCallback(() => {
    setMap(new Map());
  }, []);

  return [map, { set, setAll, remove, reset }];
}
```