# `symbols` — Kraken symbol-mapping table

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

The Kraken public ticker addresses pairs by non-standard names — `XXBTZUSD`
for BTC/USD, `XETHZUSD` for ETH/USD, `XDGUSD` for DOGE/USD — using the
asset-prefix convention (`X` for native crypto assets, `Z` for fiat) inherited
from its early-2014 instrument schema. Every consumer of the `KrakenProvider`
wants to address rates by the Suaveplan-standard symbol (`BTC`, `ETH`,
`DOGE`), so the provider needs a stable bidirectional lookup table that
normalises both directions in O(1).

This module owns that table. It exports the frozen forward map
(`KRAKEN_SYMBOL_MAP`), the derived frozen reverse map
(`KRAKEN_PAIR_TO_SYMBOL`), and a `mergeSymbolMap` helper for callers who
need to extend coverage without forking the package.

## Features

- 12 canonical Suaveplan symbols mapped to their Kraken pair names: BTC,
  ETH, SOL, USDT, DOT, ADA, LINK, AVAX, ATOM, LTC, DOGE, XRP
- Forward + reverse maps both `Object.freeze`-d for identity stability and
  cheap memoised lookups in the hot path
- `mergeSymbolMap(extras)` for caller-supplied extensions — returns a fresh
  forward + reverse pair without mutating the canonical maps
- Zero runtime dependencies, universal

## Usage: Basic

```ts
import {
 KRAKEN_PAIR_TO_SYMBOL,
 KRAKEN_SYMBOL_MAP,
} from "@suaveplan/currency-provider-kraken/symbols/symbols";

console.log(KRAKEN_SYMBOL_MAP.BTC); // "XXBTZUSD"
console.log(KRAKEN_PAIR_TO_SYMBOL.XXBTZUSD); // "BTC"
```

## Usage: Advanced

```ts
import { mergeSymbolMap } from "@suaveplan/currency-provider-kraken/symbols/symbols";

// Extend with a pair Kraken added after this release shipped.
const { forward, reverse } = mergeSymbolMap({
 MATIC: "MATICUSD",
 APT: "APTUSD",
});

console.log(forward.MATIC); // "MATICUSD"
console.log(reverse.MATICUSD); // "MATIC"

// Original maps are unchanged — `mergeSymbolMap` never mutates them.
console.log("MATIC" in KRAKEN_SYMBOL_MAP); // false
```

## API Reference

| Export | Kind | Description |
|---|---|---|
| `KRAKEN_SYMBOL_MAP` | `Readonly<Record<string, string>>` | Frozen forward map: 12 Suaveplan symbols → Kraken pair name. |
| `KRAKEN_PAIR_TO_SYMBOL` | `Readonly<Record<string, string>>` | Frozen reverse map derived at module load from the forward map. |
| `MergedSymbolMaps` | `interface` | Shape returned by `mergeSymbolMap` — `{ forward, reverse }`, both `Readonly<Record<string, string>>`. |
| `mergeSymbolMap(extras?)` | `(Readonly<Record<string, string>> \| undefined) => MergedSymbolMaps` | Returns the canonical maps when `extras` is empty/undefined; otherwise returns fresh forward + reverse maps with the extras merged on top. |

## Implementation Notes

- The Kraken instrument schema mixes legacy `X<base>Z<quote>` pairs (`XXBTZUSD`)
  with flat `<base>USD` pairs (`SOLUSD`, `DOTUSD`) added after the schema
  redesign. The map captures both forms so callers don't have to.
- The forward map is intentionally small. Kraken lists hundreds of pairs;
  the 12 included here are the high-volume subset that match the upstream
  9-provider bundle's coverage. Callers needing more symbols use the
  `extraSymbols` constructor field on `KrakenProvider` (which calls
  `mergeSymbolMap` internally) or call `mergeSymbolMap` directly when they
  want the maps for their own logic.
- `mergeSymbolMap` is a hot-path-aware fast path: when `extras` is empty or
  undefined, it returns the canonical maps by reference without allocating.
- Both canonical maps are frozen, so `Object.assign(KRAKEN_SYMBOL_MAP, …)`
  silently fails in non-strict mode and throws in strict mode — making
  accidental mutation impossible.
- Determinism: iteration order of `Object.entries(KRAKEN_SYMBOL_MAP)` is
  property-insertion order per the ES2015 spec, so derived structures
  (including the reverse map and merged outputs) have deterministic ordering
  for golden-file tests.