first commit

docs/money/finance/currency-provider-kraken/src/symbols/symbols.md

@@ -0,0 +1,90 @@
+# `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.