bitbank-lab-mcp 0.5.2 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (186) hide show
  1. package/lib/asset-code.ts +2 -42
  2. package/lib/bounded-expiring-set.ts +12 -156
  3. package/lib/cache.ts +0 -14
  4. package/lib/calendar.ts +11 -110
  5. package/lib/candle-fetch.ts +5 -84
  6. package/lib/candle-utils.ts +0 -15
  7. package/lib/candle-validate.ts +6 -88
  8. package/lib/conversions.ts +1 -19
  9. package/lib/datetime.ts +6 -109
  10. package/lib/depth-analysis.ts +1 -14
  11. package/lib/error.ts +1 -17
  12. package/lib/fees.ts +6 -71
  13. package/lib/formatter.ts +39 -106
  14. package/lib/get-depth.ts +11 -20
  15. package/lib/http.ts +7 -70
  16. package/lib/indicator-config.ts +1 -13
  17. package/lib/indicators.ts +19 -207
  18. package/lib/logger.ts +7 -47
  19. package/lib/ma-snapshot-utils.ts +4 -8
  20. package/lib/math.ts +1 -45
  21. package/lib/pair-code.ts +4 -70
  22. package/lib/pairs.ts +9 -133
  23. package/lib/pattern-diagrams.ts +16 -85
  24. package/lib/price.ts +46 -22
  25. package/lib/provisional-bar.ts +3 -32
  26. package/lib/result.ts +2 -32
  27. package/lib/tickers.ts +3 -26
  28. package/lib/trigger-price.ts +1 -11
  29. package/lib/tx-archive.ts +2 -43
  30. package/lib/tx-fetch.ts +41 -259
  31. package/lib/validate.ts +4 -32
  32. package/lib/volatility.ts +0 -64
  33. package/lib/warning-propagation.ts +0 -32
  34. package/package.json +5 -5
  35. package/src/env.ts +2 -9
  36. package/src/handlers/analyzeCandlePatternsHandler.ts +16 -34
  37. package/src/handlers/analyzeFibonacciHandler.ts +0 -2
  38. package/src/handlers/analyzeIndicatorsHandler.ts +31 -54
  39. package/src/handlers/analyzeMarketSignalHandler.ts +10 -28
  40. package/src/handlers/analyzeMyPortfolioHandler.ts +917 -1479
  41. package/src/handlers/detectPatternsDebugView.ts +407 -0
  42. package/src/handlers/detectPatternsHandler.ts +11 -22
  43. package/src/handlers/detectPatternsViewsHandler.ts +105 -986
  44. package/src/handlers/getTickersJpyHandler.ts +0 -5
  45. package/src/handlers/getVolatilityMetricsHandler.ts +10 -60
  46. package/src/handlers/portfolio/calc.ts +136 -852
  47. package/src/handlers/portfolio/calendar.ts +1 -36
  48. package/src/handlers/portfolio/fetch.ts +25 -373
  49. package/src/handlers/portfolio/holdings.ts +471 -0
  50. package/src/handlers/portfolio/pagination.ts +83 -0
  51. package/src/handlers/portfolio/types.ts +25 -424
  52. package/src/handlers/renderChartSvgHandler.ts +0 -4
  53. package/src/handlers/runBacktestHandler.ts +0 -1
  54. package/src/lib/bitbank-errors.ts +1 -18
  55. package/src/mcp-apps-hydration.ts +7 -83
  56. package/src/mcp-apps-meta.ts +3 -29
  57. package/src/private/auth.ts +2 -37
  58. package/src/private/client.ts +53 -84
  59. package/src/private/config.ts +3 -33
  60. package/src/private/confirmation.ts +14 -137
  61. package/src/private/elicitation.ts +16 -277
  62. package/src/private/execute-gate.ts +27 -0
  63. package/src/private/preview-confirmation.ts +67 -0
  64. package/src/private/request-state.ts +8 -116
  65. package/src/private/schemas.ts +14 -279
  66. package/src/private/tool-error.ts +1 -38
  67. package/src/prompts/intermediate.ts +0 -27
  68. package/src/prompts/shared.ts +0 -1
  69. package/src/resources/app-resources.ts +1 -37
  70. package/src/schema/analysis.ts +30 -76
  71. package/src/schema/backtest.ts +0 -4
  72. package/src/schema/base.ts +22 -115
  73. package/src/schema/candle-validate.ts +0 -6
  74. package/src/schema/chart.ts +18 -39
  75. package/src/schema/index.ts +0 -2
  76. package/src/schema/indicators.ts +9 -13
  77. package/src/schema/market-data.ts +17 -50
  78. package/src/schema/pairs.ts +0 -7
  79. package/src/schema/patterns.ts +54 -217
  80. package/src/schema/types.ts +0 -11
  81. package/src/schema/ui.ts +1 -7
  82. package/src/schemas.ts +0 -5
  83. package/src/server.ts +13 -76
  84. package/src/tool-definition.ts +2 -39
  85. package/src/tool-registry.ts +5 -62
  86. package/src/ui-snapshot-cache.ts +7 -80
  87. package/tools/analyze_bb_snapshot.ts +1 -12
  88. package/tools/analyze_candle_patterns.ts +12 -158
  89. package/tools/analyze_currency_strength.ts +2 -27
  90. package/tools/analyze_ema_snapshot.ts +1 -6
  91. package/tools/analyze_fibonacci.ts +4 -59
  92. package/tools/analyze_ichimoku_snapshot.ts +28 -61
  93. package/tools/analyze_indicators.ts +38 -61
  94. package/tools/analyze_market_signal.ts +7 -41
  95. package/tools/analyze_mtf_fibonacci.ts +2 -29
  96. package/tools/analyze_mtf_sma.ts +1 -13
  97. package/tools/analyze_sma_snapshot.ts +1 -5
  98. package/tools/analyze_stoch_snapshot.ts +1 -6
  99. package/tools/analyze_support_resistance.ts +7 -59
  100. package/tools/analyze_volume_profile.ts +52 -115
  101. package/tools/chart/depth-paths.ts +37 -0
  102. package/tools/chart/ichimoku-cloud.ts +0 -17
  103. package/tools/chart/render-depth.ts +16 -52
  104. package/tools/chart/render-sub-panels.ts +1 -7
  105. package/tools/chart/svg-utils.ts +0 -18
  106. package/tools/detect_macd_cross.ts +1 -19
  107. package/tools/detect_patterns.ts +157 -219
  108. package/tools/detect_whale_events.ts +1 -8
  109. package/tools/get_candles.ts +74 -316
  110. package/tools/get_flow_metrics.ts +21 -184
  111. package/tools/get_orderbook.ts +28 -88
  112. package/tools/get_ticker.ts +0 -11
  113. package/tools/get_tickers_jpy.ts +12 -20
  114. package/tools/get_transactions.ts +10 -53
  115. package/tools/get_ui_snapshot.ts +4 -30
  116. package/tools/get_volatility_metrics.ts +7 -44
  117. package/tools/patterns/aftermath.ts +7 -27
  118. package/tools/patterns/bar-thresholds.ts +6 -97
  119. package/tools/patterns/candidate-filter.ts +5 -70
  120. package/tools/patterns/config.ts +113 -507
  121. package/tools/patterns/detect_doubles.ts +289 -1263
  122. package/tools/patterns/detect_hs.ts +125 -738
  123. package/tools/patterns/detect_pennants.ts +22 -165
  124. package/tools/patterns/detect_triangles.ts +48 -234
  125. package/tools/patterns/detect_triples.ts +495 -1756
  126. package/tools/patterns/detect_wedges.ts +472 -398
  127. package/tools/patterns/helpers.ts +39 -460
  128. package/tools/patterns/index.ts +1 -9
  129. package/tools/patterns/min-bars.ts +7 -80
  130. package/tools/patterns/mutual-exclusion.ts +10 -121
  131. package/tools/patterns/period.ts +7 -50
  132. package/tools/patterns/ranking.ts +1 -39
  133. package/tools/patterns/regression.ts +38 -42
  134. package/tools/patterns/reversal-gate.ts +6 -90
  135. package/tools/patterns/scan-window.ts +4 -95
  136. package/tools/patterns/scoring.ts +2 -45
  137. package/tools/patterns/smoothing.ts +3 -52
  138. package/tools/patterns/structural.ts +138 -992
  139. package/tools/patterns/structure-diagnostics.ts +36 -0
  140. package/tools/patterns/swing.ts +25 -66
  141. package/tools/patterns/target-confounders.ts +12 -100
  142. package/tools/patterns/target-reach.ts +22 -364
  143. package/tools/patterns/types.ts +12 -147
  144. package/tools/patterns/wedge-helpers.ts +258 -0
  145. package/tools/prepare_chart_data.ts +20 -67
  146. package/tools/prepare_depth_data.ts +12 -49
  147. package/tools/private/analyze_my_portfolio.ts +0 -9
  148. package/tools/private/cancel_order.ts +4 -46
  149. package/tools/private/cancel_orders.ts +4 -42
  150. package/tools/private/create_order.ts +9 -72
  151. package/tools/private/get_margin_positions.ts +5 -22
  152. package/tools/private/get_margin_status.ts +1 -16
  153. package/tools/private/get_margin_trade_history.ts +2 -57
  154. package/tools/private/get_my_assets.ts +1 -19
  155. package/tools/private/get_my_deposit_withdrawal.ts +36 -137
  156. package/tools/private/get_my_orders.ts +2 -25
  157. package/tools/private/get_my_trade_history.ts +4 -35
  158. package/tools/private/get_order.ts +1 -13
  159. package/tools/private/get_orders_info.ts +2 -14
  160. package/tools/private/preview_cancel_order.ts +21 -111
  161. package/tools/private/preview_cancel_orders.ts +17 -83
  162. package/tools/private/preview_order.ts +20 -102
  163. package/tools/refresh_pairs_cache.ts +1 -9
  164. package/tools/render_candle_pattern_diagram.ts +5 -64
  165. package/tools/render_chart_svg.ts +15 -102
  166. package/tools/render_depth_svg.ts +32 -62
  167. package/tools/trading_process/index.ts +0 -4
  168. package/tools/trading_process/lib/backtest_engine.ts +12 -122
  169. package/tools/trading_process/lib/equity.ts +2 -60
  170. package/tools/trading_process/lib/fetch_candles.ts +3 -56
  171. package/tools/trading_process/lib/resolve_fee.ts +3 -36
  172. package/tools/trading_process/lib/sma.ts +1 -49
  173. package/tools/trading_process/lib/strategies/bb_breakout.ts +4 -26
  174. package/tools/trading_process/lib/strategies/filters.ts +30 -0
  175. package/tools/trading_process/lib/strategies/index.ts +0 -20
  176. package/tools/trading_process/lib/strategies/macd_cross.ts +13 -91
  177. package/tools/trading_process/lib/strategies/rsi.ts +2 -31
  178. package/tools/trading_process/lib/strategies/sma_cross.ts +6 -73
  179. package/tools/trading_process/lib/strategies/types.ts +2 -58
  180. package/tools/trading_process/lib/svg_to_png.ts +1 -22
  181. package/tools/trading_process/render_backtest_chart_generic.ts +10 -75
  182. package/tools/trading_process/run_backtest.ts +5 -54
  183. package/tools/trading_process/types.ts +4 -21
  184. package/tools/validate_candle_data.ts +0 -16
  185. package/ui/cancel-confirm/dist/cancel-confirm.html +61 -64
  186. package/ui/order-confirm/dist/order-confirm.html +61 -64
package/lib/asset-code.ts CHANGED
@@ -1,52 +1,12 @@
1
- /**
2
- * asset コード正規化ユーティリティ。
3
- *
4
- * bitbank API が返す通貨コード(`assets[].asset` / `deposits[].asset` /
5
- * `withdrawals[].asset`)を **取得境界で小文字へ揃える**ための単一実装。
6
- *
7
- * リポジトリ全体が「API が返す asset は小文字」という前提の上に立っており、
8
- * 生の `asset` を小文字リテラル(`'jpy'`)と比較する、あるいは Map のキーに使う
9
- * 箇所が 20 箇所以上ある(`portfolio/calc.ts` の JPY 判定・holdings キー・
10
- * `prices.get(asset)` 等)。大文字が 1 つでも紛れ込むと、`JPY` が「価格を引けない
11
- * 暗号資産」として純入出金から落ちる/`BTC` と `btc` で保有キーが割れて二重計上に
12
- * なる、といった破綻が同時に起きる。
13
- *
14
- * これは**防御的正規化**であり、現行 API は小文字を返す(公式 docs の JSON 例は
15
- * `"asset": "jpy"`、`docs/internal/bitbank-api-fields.md` 参照)。前提をコードに
16
- * 明文化し、破れたときに数値が壊れないようにするのが目的。
17
- *
18
- * **消費側(`portfolio/calc.ts` 等)に `.toLowerCase()` を撒かないこと。**
19
- * 正規化は取得境界(`portfolio/fetch.ts` / `/v1/user/assets` の取り込み)に集約し、
20
- * どこで担保されているかを 1 箇所に保つ。
21
- *
22
- * ユーザー入力の pair 正規化(`lib/validate.ts` の `normalizePair`)とは別レイヤー。
23
- * 混ぜないこと(あちらは入力の受け口、こちらは API レスポンスの受け口)。
24
- *
25
- * API が返す **pair シンボル**の取得境界正規化は姉妹モジュール `lib/pair-code.ts`。
26
- * pair から導出した asset(`replace('_jpy', '')`)は本モジュールが担保する小文字空間に
27
- * 乗る必要があるため、両者は同じ境界方針で揃えてある。
28
- */
1
+ // 正規化は取得境界に集約し、消費側(portfolio/calc.ts 等)に .toLowerCase() を撒かない。大文字が混ざると JPY が純入出金から落ち、保有キーが割れて二重計上になる。
29
2
 
30
- /**
31
- * API 由来の asset コードを小文字へ正規化する。
32
- *
33
- * 前後の空白も落とす(`normalizePair` と同方針)。asset コードは英数字のみのため、
34
- * ロケール依存の `toLocaleLowerCase` ではなく `toLowerCase` を使う。
35
- */
36
3
  export function normalizeAssetCode(raw: string): string {
37
4
  return raw.trim().toLowerCase();
38
5
  }
39
6
 
40
- /**
41
- * API レスポンスのレコード配列について `asset` フィールドのみを正規化した配列を返す。
42
- *
43
- * 既に小文字(=現行 API の実挙動)なら**元のオブジェクト参照をそのまま通す**ので、
44
- * 既存レスポンスに対しては実質ノーオペ(出力は 1 バイトも変わらない)。
45
- */
46
7
  export function normalizeAssetCodes<T extends { asset: string }>(records: readonly T[]): T[] {
47
8
  return records.map((record) => {
48
- // レスポンス不正で asset が欠けていても取得層で throw させない(防御)。
49
- // 消費側では従来どおり「'jpy' でない未知資産」として扱われる。
9
+ // asset が欠けていても取得層で throw させない。
50
10
  if (typeof record.asset !== 'string') return record;
51
11
  const asset = normalizeAssetCode(record.asset);
52
12
  return asset === record.asset ? record : { ...record, asset };
@@ -1,110 +1,31 @@
1
- /**
2
- * TTL + 件数上限つきの「使用済み記録」セット(replay ガード用の共通データ構造)。
3
- *
4
- * 使用済みの confirmation token(`src/private/confirmation.ts`)や requestState の nonce
5
- * (`src/private/request-state.ts`)のように、**一度使ったキーを TTL の間だけ覚えておき、
6
- * 再提示を拒否する**用途のために切り出したもの。
7
- *
8
- * 設計上の最重要ルール — **生存エントリを追い出さない**:
9
- * 容量を空けるために未期限切れのエントリを LRU 等で退避すると、その token / nonce は
10
- * 「未使用」状態に巻き戻り、replay が黙って通る。メモリ上限のためにワンタイム性を
11
- * 犠牲にしてはいけないので、容量到達時は
12
- * 1. 期限切れエントリを purge する(古い=挿入順の先頭側から)
13
- * 2. それでも空きが無ければ `add` を失敗させる
14
- * の順で処理し、呼び出し側に実行を拒否させる(fail-closed)。
15
- *
16
- * ワンタイム性の保証範囲:
17
- * 保証されるのは `expiresAtMs` までの間だけ。期限切れ後は記録が消えるため、
18
- * 同じキーを再び `add` できる。呼び出し側は「記録の有無」とは別に、token / nonce 自身の
19
- * 有効期限も必ず検証すること(`validateToken` が期限チェックを先に行うのと同じ理由)。
20
- *
21
- * 非有限のタイムスタンプ:
22
- * `expiresAtMs` は confirmation フローでクライアントを往復しうる値なので、外部由来として扱う。
23
- * 非有限値(NaN / ±Infinity)は**状態を一切変更する前に**弾き、`invalid_expiry` で拒否する。
24
- * `nowMs` は呼び出し側の時計(既定 `Date.now()`)なので、非有限値はプログラミングエラーとして
25
- * `TypeError` を投げる。どちらも黙って劣化させると replay が通る(理由は各メソッドのコメント)。
26
- *
27
- * ログ:
28
- * このモジュールは key の本文を保持するだけで、**どこにも出力しない**。
29
- * token / nonce は `.claude/rules/sensitive-data.md` の CRITICAL 分類にあたるため、
30
- * 呼び出し側もログには `stats()` が返す件数系のメタ情報のみを記録すること。
31
- *
32
- * 使い方:
33
- * const used = new BoundedExpiringSet();
34
- * used.startCleanupTimer();
35
- * const res = used.add(token, expiresAt);
36
- * if (!res.added) return reject(res.reason);
37
- */
1
+ // 生存エントリを追い出さない。容量のために未期限切れを退避すると token / nonce が未使用に巻き戻り replay が通るので、空きが作れなければ add を失敗させる(fail-closed)。
2
+ // key は保持するだけでどこにも出力しない(token / nonce は sensitive-data の CRITICAL)。呼び出し側も stats() の件数だけをログに出す。
38
3
 
39
- /**
40
- * 記録件数の既定上限。
41
- *
42
- * 算出根拠 — TTL × 想定ピークレート:
43
- * - 保持期間: 最長 300 秒。confirmation token は既定 60 秒(`ORDER_CONFIRM_TTL_MS`)で
44
- * 上限 300 秒(`MAX_TTL_MS`)、requestState の nonce は 300 秒(`REQUEST_STATE_TTL_SECONDS`)。
45
- * - 想定ピーク確認レート: 20 件/秒。HITL 確認は人手起点なので実運用では 1 件/秒にも届かないが、
46
- * 自動化クライアントの連投を見込んで 20 倍のマージンを取る。
47
- * → 300 秒 × 20 件/秒 = 6,000 件。切り上げて 10,000 件。
48
- *
49
- * メモリ概算 — 1 エントリあたり:
50
- * - key: HMAC-SHA256 の hex = 64 文字 ≈ 64B + 文字列ヘッダ ≈ 24B → 約 88B
51
- * (nonce は 32 文字なので約半分。長い方に合わせて見積もる)
52
- * - value: expiresAt。ms epoch は Smi 範囲外なので heap number 扱い → 約 16B
53
- * - Map のエントリ配列 + ハッシュ表(負荷率の余白込み) → 約 96B
54
- * → 合計 約 200B/件。10,000 件で 約 2MB。`MAX_ENTRIES_CEILING` の 100,000 件でも 約 20MB。
55
- */
4
+ // TTL 最長 300 秒 × 想定ピーク 20 件/秒 = 6,000 件を切り上げた値(1 件約 200B で約 2MB)。
56
5
  export const DEFAULT_MAX_ENTRIES = 10_000;
57
6
 
58
- /**
59
- * 上限値の clamp 先(≈20MB 相当)。
60
- * 環境変数やコンストラクタ引数でこれを超える値を渡してもここで頭打ちにする。
61
- */
62
7
  export const MAX_ENTRIES_CEILING = 100_000;
63
8
 
64
9
  /** 既定の定期 purge 間隔: 60秒(`src/private/confirmation.ts` の `CLEANUP_INTERVAL_MS` と揃える) */
65
10
  export const DEFAULT_PURGE_INTERVAL_MS = 60_000;
66
11
 
67
- /** 件数上限を上書きする環境変数名。不正値は `DEFAULT_MAX_ENTRIES` にフォールバックする。 */
68
12
  export const MAX_ENTRIES_ENV = 'REPLAY_GUARD_MAX_ENTRIES';
69
13
 
70
- /** `add` が失敗した理由 */
71
- export type AddRejectReason =
72
- /** 同じ key が生存中の記録として既に存在する(= replay) */
73
- | 'already_recorded'
74
- /** 件数上限に達しており、期限切れを purge しても空きを作れなかった */
75
- | 'capacity_exceeded'
76
- /** `expiresAtMs` が非有限値(NaN / ±Infinity)だった */
77
- | 'invalid_expiry';
14
+ export type AddRejectReason = 'already_recorded' | 'capacity_exceeded' | 'invalid_expiry';
78
15
 
79
- /**
80
- * `add` の結果。
81
- *
82
- * 判別可能ユニオンにしてあるので、`reason` を読むには必ず `added` で絞り込む必要がある。
83
- * `if (!res.added)` を書かずに理由を参照することはできない(呼び出し側が黙って握り潰せない)。
84
- */
16
+ // 判別可能ユニオンにして、added で絞り込まないと reason を読めないようにしている(呼び出し側が黙って握り潰せない)。
85
17
  export type AddResult = { readonly added: true } | { readonly added: false; readonly reason: AddRejectReason };
86
18
 
87
- /** 観測用カウンタ。key の本文は一切含まない。 */
88
19
  export interface BoundedExpiringSetStats {
89
- /** 現在の記録件数(期限切れが残っている場合は含む) */
90
20
  size: number;
91
- /** 有効な件数上限(clamp 適用後) */
92
21
  maxEntries: number;
93
- /** 除去した期限切れエントリの累計 */
94
22
  purgedTotal: number;
95
- /** 容量超過で拒否した `add` の累計 */
96
23
  rejectedTotal: number;
97
- /** 非有限の `expiresAtMs` で拒否した `add` の累計(改竄・呼び出し側バグの検知用) */
98
24
  invalidExpiryTotal: number;
99
25
  }
100
26
 
101
27
  export interface BoundedExpiringSetOptions {
102
- /**
103
- * 件数上限。省略時は環境変数 `REPLAY_GUARD_MAX_ENTRIES`、それも無ければ `DEFAULT_MAX_ENTRIES`。
104
- * 非有限値・1 未満はデフォルトへフォールバックし、`MAX_ENTRIES_CEILING` で clamp する。
105
- */
106
28
  maxEntries?: number;
107
- /** 定期 purge の間隔(ms)。非有限値・0 以下はデフォルトへフォールバック。 */
108
29
  purgeIntervalMs?: number;
109
30
  }
110
31
 
@@ -114,7 +35,6 @@ function normalizeMaxEntries(value: number | undefined): number {
114
35
  return Math.min(Math.floor(value), MAX_ENTRIES_CEILING);
115
36
  }
116
37
 
117
- /** 環境変数の生値を数値化する。未設定・空文字は undefined(=デフォルト採用) */
118
38
  function envMaxEntries(): number | undefined {
119
39
  const raw = process.env[MAX_ENTRIES_ENV];
120
40
  if (!raw) return undefined;
@@ -127,12 +47,7 @@ function normalizePurgeInterval(value: number | undefined): number {
127
47
  return value;
128
48
  }
129
49
 
130
- /**
131
- * `nowMs` が非有限だと期限比較(`nowMs > expiresAt` / `nowMs <= expiresAt`)が全て false になり、
132
- * 「生存エントリを期限切れとみなして削除 → 同じ key を再記録できる」= replay が黙って通る。
133
- * `nowMs` は呼び出し側の時計(既定 `Date.now()`)でありユーザー入力ではないので、
134
- * 劣化させずプログラミングエラーとして投げる。メッセージに key は含めない。
135
- */
50
+ // nowMs が非有限だと期限比較が全て false になり replay が黙って通るので、劣化させず TypeError を投げる(メッセージに key は含めない)。
136
51
  function assertFiniteNow(nowMs: number, method: string): void {
137
52
  if (!Number.isFinite(nowMs)) {
138
53
  throw new TypeError(`BoundedExpiringSet.${method}: nowMs must be a finite number`);
@@ -140,14 +55,7 @@ function assertFiniteNow(nowMs: number, method: string): void {
140
55
  }
141
56
 
142
57
  export class BoundedExpiringSet {
143
- /**
144
- * key → expiresAt(ms)。
145
- *
146
- * Map は挿入順を保持するので、**TTL が呼び出し間で一定であれば挿入順 = 期限順**になる。
147
- * この性質を使って通常経路では先頭側だけを走査し(`purgeExpiredPrefix`)、最初に
148
- * 生存エントリへ当たった時点で打ち切る。TTL が不揃いな呼び出し方をされると先頭走査では
149
- * 取りこぼすため、容量到達時のみ全走査(`purgeExpired`)にフォールバックする。
150
- */
58
+ // 挿入順 = 期限順(TTL 一定のとき)を使って通常は先頭だけを走査し、容量到達時のみ全走査にフォールバックする。
151
59
  private readonly store = new Map<string, number>();
152
60
 
153
61
  private readonly maxEntriesValue: number;
@@ -162,45 +70,21 @@ export class BoundedExpiringSet {
162
70
  this.purgeIntervalMs = normalizePurgeInterval(opts.purgeIntervalMs);
163
71
  }
164
72
 
165
- /** 有効な件数上限(clamp 適用後) */
166
73
  get maxEntries(): number {
167
74
  return this.maxEntriesValue;
168
75
  }
169
76
 
170
- /**
171
- * key を使用済みとして記録する。
172
- *
173
- * - 未記録(または記録が期限切れ)かつ空きがある → `{ added: true }`
174
- * - 生存中の記録が既にある → `{ added: false, reason: 'already_recorded' }`(replay)
175
- * - 期限切れを purge しても空きが作れない → `{ added: false, reason: 'capacity_exceeded' }`
176
- * - `expiresAtMs` が非有限値 → `{ added: false, reason: 'invalid_expiry' }`(状態は変更しない)
177
- *
178
- * 容量を空けるために生存エントリを追い出すことはない。呼び出し側は
179
- * `added === false` の場合、理由を問わず対象の操作を拒否すること。
180
- *
181
- * @param key - 記録するキー(token / nonce 等)。ログには出さない。
182
- * @param expiresAtMs - 記録の有効期限(epoch ms)。有限値のみ受け付ける。過去を渡した場合は
183
- * 直後に期限切れ扱いになる。TTL の上限クランプは呼び出し側の責務
184
- * (`confirmation.ts` の `MAX_TTL_MS` 等)で、ここでは長さの妥当性までは見ない。
185
- * @param nowMs - 現在時刻(テスト用にオーバーライド可能)。非有限値は `TypeError`。
186
- * @throws {TypeError} `nowMs` が非有限値の場合
187
- */
77
+ // added === false なら理由を問わず操作を拒否させる。TTL の上限クランプは呼び出し側の責務で、ここでは長さを見ない。
188
78
  add(key: string, expiresAtMs: number, nowMs: number = Date.now()): AddResult {
189
79
  assertFiniteNow(nowMs, 'add');
190
80
 
191
- // 非有限の expiresAt は「状態を触る前」に弾く(下の purgeExpiredPrefix より必ず先)。
192
- // NaN … 全比較が false になるため has() / purgeExpired() からは「永久に生存」に見える一方、
193
- // purgeExpiredPrefix では期限切れ扱いで削除される。判定が経路ごとに食い違い、
194
- // 記録済みのはずの key が黙って消えて replay が通る。
195
- // Infinity … 期限切れにならず容量を専有し続ける。さらに先頭走査がそこで打ち切られるため、
196
- // 高速パスが恒久的に機能しなくなる。
81
+ // 非有限の expiresAt は状態を触る前に弾く。NaN は経路ごとに生存 / 期限切れの判定が食い違い、Infinity は容量を専有して先頭走査を止める。
197
82
  if (!Number.isFinite(expiresAtMs)) {
198
83
  this.invalidExpiryTotal++;
199
84
  return { added: false, reason: 'invalid_expiry' };
200
85
  }
201
86
 
202
- // 通常経路の掃除。先頭が生存していれば比較 1 回で抜けるので、
203
- // エントリ数に比例した CPU 消費(= CPU 側の攻撃面)を避けられる。
87
+ // 先頭が生存していれば比較 1 回で抜けるので、エントリ数に比例した CPU 消費を避けられる。
204
88
  this.purgeExpiredPrefix(nowMs);
205
89
 
206
90
  const existing = this.store.get(key);
@@ -212,10 +96,8 @@ export class BoundedExpiringSet {
212
96
  }
213
97
 
214
98
  if (this.store.size >= this.maxEntriesValue) {
215
- // 先頭走査で足りなかった(TTL が不揃い等)→ 全走査で最後の空きを探す
216
99
  this.purgeExpired(nowMs);
217
100
  if (this.store.size >= this.maxEntriesValue) {
218
- // 生存エントリの追い出しはしない。ここで失敗させ、呼び出し側に拒否させる。
219
101
  this.rejectedTotal++;
220
102
  return { added: false, reason: 'capacity_exceeded' };
221
103
  }
@@ -225,12 +107,6 @@ export class BoundedExpiringSet {
225
107
  return { added: true };
226
108
  }
227
109
 
228
- /**
229
- * key が生存中の記録として存在するか。期限切れは「存在しない」として扱い、
230
- * 該当エントリはこの場で除去する(アクセス時 purge、O(1))。
231
- *
232
- * @throws {TypeError} `nowMs` が非有限値の場合
233
- */
234
110
  has(key: string, nowMs: number = Date.now()): boolean {
235
111
  assertFiniteNow(nowMs, 'has');
236
112
  const expiresAt = this.store.get(key);
@@ -243,11 +119,6 @@ export class BoundedExpiringSet {
243
119
  return true;
244
120
  }
245
121
 
246
- /**
247
- * 期限切れエントリを全走査で除去し、除去件数を返す。
248
- *
249
- * @throws {TypeError} `nowMs` が非有限値の場合
250
- */
251
122
  purgeExpired(nowMs: number = Date.now()): number {
252
123
  assertFiniteNow(nowMs, 'purgeExpired');
253
124
  let purged = 0;
@@ -261,14 +132,7 @@ export class BoundedExpiringSet {
261
132
  return purged;
262
133
  }
263
134
 
264
- /**
265
- * 挿入順の先頭側から期限切れを除去し、最初の生存エントリで打ち切る。
266
- * TTL が一定という前提の下では全期限切れを除去できる(前提が崩れた場合の
267
- * 取りこぼしは `add` の容量到達時に `purgeExpired` がカバーする)。
268
- *
269
- * 事前条件: `nowMs` が有限であること(呼び出し元の `add` が検証済み)。
270
- * 格納値も `add` が有限値のみ通すので、比較が NaN で崩れることはない。
271
- */
135
+ // 事前条件: nowMs が有限(呼び出し元の add が検証済み)。
272
136
  private purgeExpiredPrefix(nowMs: number): number {
273
137
  let purged = 0;
274
138
  for (const [key, expiresAt] of this.store) {
@@ -281,17 +145,14 @@ export class BoundedExpiringSet {
281
145
  return purged;
282
146
  }
283
147
 
284
- /** 現在の記録件数(期限切れが残っている場合は含む) */
285
148
  size(): number {
286
149
  return this.store.size;
287
150
  }
288
151
 
289
- /** 全記録を破棄する(テスト用 / プロセス内リセット用)。累計カウンタは保持する。 */
290
152
  clear(): void {
291
153
  this.store.clear();
292
154
  }
293
155
 
294
- /** 観測用カウンタのスナップショット。key の本文は含まない。 */
295
156
  stats(): BoundedExpiringSetStats {
296
157
  return {
297
158
  size: this.store.size,
@@ -302,10 +163,7 @@ export class BoundedExpiringSet {
302
163
  };
303
164
  }
304
165
 
305
- /**
306
- * 定期 purge を開始する(重複起動しない)。
307
- * アクセス時 purge だけに頼ると、無アクセス期間のエントリが TTL 超過後も残り続ける。
308
- */
166
+ // アクセス時 purge だけだと無アクセス期間のエントリが TTL 超過後も残り続ける。
309
167
  startCleanupTimer(): void {
310
168
  if (this.cleanupTimerId != null) return;
311
169
  this.cleanupTimerId = setInterval(() => this.purgeExpired(), this.purgeIntervalMs);
@@ -315,7 +173,6 @@ export class BoundedExpiringSet {
315
173
  }
316
174
  }
317
175
 
318
- /** 定期 purge を停止する(複数回呼んでも安全)。 */
319
176
  stopCleanupTimer(): void {
320
177
  if (this.cleanupTimerId != null) {
321
178
  clearInterval(this.cleanupTimerId);
@@ -323,7 +180,6 @@ export class BoundedExpiringSet {
323
180
  }
324
181
  }
325
182
 
326
- /** 定期 purge タイマーが稼働中かどうか。 */
327
183
  isCleanupTimerActive(): boolean {
328
184
  return this.cleanupTimerId != null;
329
185
  }
package/lib/cache.ts CHANGED
@@ -1,16 +1,5 @@
1
- /**
2
- * Shared in-memory TTL cache with optional max-entry eviction (FIFO).
3
- *
4
- * Usage:
5
- * const c = new TtlCache<MyData>({ ttlMs: 30_000, maxEntries: 20 });
6
- * c.set('key', data);
7
- * const hit = c.get('key'); // undefined if expired or absent
8
- */
9
-
10
1
  export interface TtlCacheOptions {
11
- /** Time-to-live in milliseconds. */
12
2
  ttlMs: number;
13
- /** Maximum number of entries. Oldest entry is evicted when exceeded. Default: no limit. */
14
3
  maxEntries?: number;
15
4
  }
16
5
 
@@ -29,7 +18,6 @@ export class TtlCache<V> {
29
18
  this.maxEntries = opts.maxEntries ?? Infinity;
30
19
  }
31
20
 
32
- /** Return cached value if present and not expired, otherwise `undefined`. */
33
21
  get(key: string): V | undefined {
34
22
  const entry = this.store.get(key);
35
23
  if (!entry) return undefined;
@@ -40,7 +28,6 @@ export class TtlCache<V> {
40
28
  return entry.value;
41
29
  }
42
30
 
43
- /** Store a value. Evicts the oldest entry when `maxEntries` is reached. */
44
31
  set(key: string, value: V): void {
45
32
  if (this.store.size >= this.maxEntries && !this.store.has(key)) {
46
33
  const oldest = this.store.keys().next().value;
@@ -51,7 +38,6 @@ export class TtlCache<V> {
51
38
  this.store.set(key, { value, ts: Date.now() });
52
39
  }
53
40
 
54
- /** Check existence without returning the value. */
55
41
  has(key: string): boolean {
56
42
  return this.get(key) !== undefined;
57
43
  }
package/lib/calendar.ts CHANGED
@@ -1,63 +1,29 @@
1
- /**
2
- * 暦日(カレンダーデー)プリミティブ。
3
- *
4
- * 「ある tz の暦日はいつ始まっていつ終わるか」「その瞬間はどの暦日キーか」
5
- * 「2 時刻の間にどの暦日キーが挟まるか」「その暦日はもう完了したか」だけを扱う。
6
- * 上流 API の仕様(bitbank の約定アーカイブは UTC 暦日単位、/candlestick は UTC 暦日
7
- * chunk 等)はドメイン層(`lib/tx-archive.ts` など)の責務であり、本モジュールは持たない。
8
- *
9
- * ## tz は必ず明示引数で渡す
10
- *
11
- * 既定値を置かない。同じ関数名で暦の基準が呼び出し箇所ごとに違う——現に
12
- * `date: 'YYYYMMDD'` の解釈が UTC 暦日と JST 暦日に割れている——という問題を
13
- * lib 側に持ち込まないため。`'UTC'` も普通の tz として渡す。
14
- *
15
- * ## 入力が不正なときの挙動
16
- *
17
- * - **tz が不正 / ms が非有限** → `TypeError` を throw する。呼び出し側のバグであり、
18
- * 黙って `NaN` や `'Invalid Date'` を伝播させると原因の遠い場所で壊れる。
19
- * ユーザー入力の tz は `isSupportedTimeZone()` で先に正規化すること。
20
- * - **キー文字列の形式不正 / 実在しない日付** → `null`(`parse*`)または `false`(`is*`)を返す。
21
- * こちらはユーザー入力由来なので throw しない。
22
- *
23
- * 素の `Date` コンストラクタは banned(`.claude/hooks/post-ts-lint.sh`)。日時計算は
24
- * `lib/datetime.ts` の dayjs(utc / timezone / customParseFormat プラグイン適用済み)に集約する。
25
- */
1
+ // tz は既定値を置かず必ず明示引数で渡す(date の解釈が UTC 暦日と JST 暦日に割れている問題を lib に持ち込まない)。
2
+ // tz 不正・非有限 ms は呼び出し側のバグなので TypeError、キー文字列の不正はユーザー入力由来なので null / false を返す。
26
3
 
27
4
  import { dayjs } from './datetime.js';
28
5
 
29
- /** 暦日キーの形式(YYYYMMDD)。実在日かどうかは見ない。 */
30
6
  const DAY_KEY_PATTERN = /^\d{8}$/;
31
7
 
32
- /** 暦年キーの形式(YYYY)。 */
33
8
  const YEAR_KEY_PATTERN = /^\d{4}$/;
34
9
 
35
- /** 暦日キー(`YYYYMMDD`)。文字列の辞書順が時系列順と一致する。 */
10
+ /** 文字列の辞書順が時系列順と一致する。 */
36
11
  export type DayKey = string;
37
12
 
38
- /** 暦年キー(`YYYY`)。 */
39
13
  export type YearKey = string;
40
14
 
41
- /** 暦上の 1 区間。 */
42
15
  export interface CalendarSpan {
43
- /** 区間の最初のミリ秒。 */
44
16
  readonly startMs: number;
45
- /** 区間の最後のミリ秒(**inclusive**)。次の区間の開始 - 1 に等しい。 */
17
+ /** inclusive(次の区間の開始 - 1)。 */
46
18
  readonly endMs: number;
47
19
  }
48
20
 
49
- /**
50
- * dayjs(= Intl)が解釈できる tz 文字列か。空文字・未定義・不正な IANA 名は false。
51
- *
52
- * 不正 tz を既定値へ倒すかどうかは呼び出し側のポリシーなので、本モジュールでは判定だけ提供する。
53
- * 例: `const safeTz = isSupportedTimeZone(tz) ? tz : 'Asia/Tokyo';`
54
- */
21
+ // 不正 tz を既定値へ倒すかは呼び出し側のポリシーなので、判定だけを提供する。
55
22
  export function isSupportedTimeZone(tz: unknown): tz is string {
56
23
  if (typeof tz !== 'string' || tz.length === 0) return false;
57
24
  try {
58
25
  return dayjs(0).tz(tz).isValid();
59
26
  } catch {
60
- // Intl は不正な tz 名に RangeError を投げる
61
27
  return false;
62
28
  }
63
29
  }
@@ -80,60 +46,41 @@ function inTz(ms: number, tz: string, label = 'ms'): dayjs.Dayjs {
80
46
  return dayjs(ms).tz(tz);
81
47
  }
82
48
 
83
- /**
84
- * ms が属する tz 暦日の最初のミリ秒。
85
- *
86
- * DST 開始が 00:00 の tz(例: 2017-10-15 の America/Sao_Paulo は 00:00 が存在しない)では
87
- * その暦日に実在する最初の瞬間(01:00)を返す。
88
- */
49
+ // DST 開始が 00:00 の tz ではその暦日に実在する最初の瞬間(01:00)を返す。
89
50
  export function startOfDayMs(ms: number, tz: string): number {
90
51
  return inTz(ms, tz).startOf('day').valueOf();
91
52
  }
92
53
 
93
- /** ms が属する tz 暦日の最後のミリ秒(23:59:59.999 相当。**inclusive**)。 */
94
54
  export function endOfDayMs(ms: number, tz: string): number {
95
55
  return inTz(ms, tz).endOf('day').valueOf();
96
56
  }
97
57
 
98
- /** ms が属する tz 暦年の最初のミリ秒(1/1 00:00:00.000 in tz)。 */
99
58
  export function startOfYearMs(ms: number, tz: string): number {
100
59
  return inTz(ms, tz).startOf('year').valueOf();
101
60
  }
102
61
 
103
- /** ms が属する tz 暦年の最後のミリ秒(12/31 23:59:59.999 in tz。**inclusive**)。 */
104
62
  export function endOfYearMs(ms: number, tz: string): number {
105
63
  return inTz(ms, tz).endOf('year').valueOf();
106
64
  }
107
65
 
108
- /** ms が属する tz 暦日のキー(`YYYYMMDD`)。 */
109
66
  export function toDayKey(ms: number, tz: string): DayKey {
110
67
  return inTz(ms, tz).format('YYYYMMDD');
111
68
  }
112
69
 
113
- /** ms が属する tz 暦年のキー(`YYYY`)。 */
114
70
  export function toYearKey(ms: number, tz: string): YearKey {
115
71
  return inTz(ms, tz).format('YYYY');
116
72
  }
117
73
 
118
- /**
119
- * `YYYYMMDD` の**形式**を満たすか。2026-02-30 のような実在しない日付も true になる。
120
- * 実在日まで確かめたい場合は `parseDayKey()` が `null` を返すかで判定する。
121
- */
74
+ /** 実在しない日付も true になる。実在日まで確かめるなら parseDayKey の null で判定する。 */
122
75
  export function isDayKeyFormat(value: unknown): value is DayKey {
123
76
  return typeof value === 'string' && DAY_KEY_PATTERN.test(value);
124
77
  }
125
78
 
126
- /** `YYYY` の形式を満たすか。 */
127
79
  export function isYearKeyFormat(value: unknown): value is YearKey {
128
80
  return typeof value === 'string' && YEAR_KEY_PATTERN.test(value);
129
81
  }
130
82
 
131
- /**
132
- * 暦日キー(`YYYYMMDD`)を tz 上の区間に変換する。形式不正・実在しない日付は `null`。
133
- *
134
- * `dayjs.tz('2026-02-30', tz)` は例外を投げずに 3/2 へ繰り上げてしまうため、
135
- * tz を当てる前に UTC の strict parse で実在日かどうかを確かめる。
136
- */
83
+ // dayjs.tz('2026-02-30', tz) は例外を投げずに 3/2 へ繰り上げるので、tz を当てる前に UTC の strict parse で実在日か確かめる。
137
84
  export function parseDayKey(key: string, tz: string): CalendarSpan | null {
138
85
  if (!isDayKeyFormat(key)) return null;
139
86
  if (!dayjs.utc(key, 'YYYYMMDD', true).isValid()) return null;
@@ -143,20 +90,7 @@ export function parseDayKey(key: string, tz: string): CalendarSpan | null {
143
90
  return { startMs: d.startOf('day').valueOf(), endMs: d.endOf('day').valueOf() };
144
91
  }
145
92
 
146
- /**
147
- * 暦日キーを tz 上の区間に変換する(**繰り上げ許容**版)。
148
- *
149
- * `parseDayKey` が実在しない日付を `null` で弾くのに対し、こちらはグレゴリオ暦の繰り上げで
150
- * 解釈する(`20260230` → 2026-03-02、`20251232` → 2026-01-01)。形式不正は `null`。
151
- *
152
- * 入力の**形式だけ**を検証して実在日を見ない層を通った値を扱う呼び出し側のための入口。
153
- * 現に `lib/validate.ts` の `validateDate` は `/^\d{8}$/` しか見ず、`get_candles` の `date` は
154
- * 繰り上げ解釈のまま anchor と fetch 範囲を組んでいる。厳密解釈へ倒すと「anchor 無効 →
155
- * 最新側 limit 本」のように結果が silent に変わるため、繰り上げるかどうかは
156
- * **呼び出し側が関数の選択として明示する**。
157
- *
158
- * 既定は `parseDayKey`(実在日を要求する方)を使うこと。
159
- */
93
+ // 繰り上げるかは呼び出し側が関数の選択として明示する(get_candles の date は繰り上げ解釈のまま anchor を組んでおり、厳密解釈にすると結果が silent に変わる)。既定は parseDayKey を使う。
160
94
  export function parseDayKeyAllowingOverflow(key: string, tz: string): CalendarSpan | null {
161
95
  if (!isDayKeyFormat(key)) return null;
162
96
  assertTimeZone(tz);
@@ -165,7 +99,6 @@ export function parseDayKeyAllowingOverflow(key: string, tz: string): CalendarSp
165
99
  return { startMs: d.startOf('day').valueOf(), endMs: d.endOf('day').valueOf() };
166
100
  }
167
101
 
168
- /** 暦年キー(`YYYY`)を tz 上の区間に変換する。形式不正は `null`。 */
169
102
  export function parseYearKey(key: string, tz: string): CalendarSpan | null {
170
103
  if (!isYearKeyFormat(key)) return null;
171
104
  assertTimeZone(tz);
@@ -174,13 +107,7 @@ export function parseYearKey(key: string, tz: string): CalendarSpan | null {
174
107
  return { startMs: d.startOf('year').valueOf(), endMs: d.endOf('year').valueOf() };
175
108
  }
176
109
 
177
- /**
178
- * 暦日キーを days 日ずらす。形式不正・実在しない日付・非整数 days は `null`。
179
- *
180
- * グレゴリオ暦の日付演算のみで、tz には依存しない(`20260301` の前日は
181
- * どの tz でも `20260228` / 閏年なら `20260229`)。ミリ秒に落とさないので
182
- * DST による 23h / 25h の日を跨いでもズレない。
183
- */
110
+ // ミリ秒に落とさないので DST による 23h / 25h の日を跨いでもズレない。
184
111
  export function shiftDayKey(key: string, days: number): DayKey | null {
185
112
  if (!isDayKeyFormat(key) || !Number.isInteger(days)) return null;
186
113
  const d = dayjs.utc(key, 'YYYYMMDD', true);
@@ -188,13 +115,6 @@ export function shiftDayKey(key: string, days: number): DayKey | null {
188
115
  return d.add(days, 'day').format('YYYYMMDD');
189
116
  }
190
117
 
191
- /**
192
- * [startMs, endMs] と交差する tz 暦日キーを昇順(inclusive)で列挙する。
193
- * `startMs > endMs` なら空配列。
194
- *
195
- * 列挙はキーの日付演算で進めるため、DST で 23h / 25h になる日や月末・閏日を跨いでも
196
- * 日が飛んだり重複したりしない。
197
- */
198
118
  export function enumerateDayKeys(startMs: number, endMs: number, tz: string): DayKey[] {
199
119
  assertFiniteMs(startMs, 'startMs');
200
120
  assertFiniteMs(endMs, 'endMs');
@@ -210,24 +130,13 @@ export function enumerateDayKeys(startMs: number, endMs: number, tz: string): Da
210
130
  return keys;
211
131
  }
212
132
 
213
- /**
214
- * 2 つの瞬間が属する tz 暦日の差(`toMs` の暦日 − `fromMs` の暦日、単位: 日)。
215
- * 同じ暦日なら 0、`toMs` が翌日なら 1、前日なら -1。
216
- *
217
- * ミリ秒差を 86400000 で割ってはいけない。DST を挟むと 23h / 25h の日が出て 1 日ぶんずれる
218
- * (`America/New_York` の 2025-01-01 → 06-16 は暦日で 166 日だが ms 差は 165 日 23 時間)。
219
- * 暦日キーの日付演算で数えるためオフセットの変化に影響されない。
220
- */
133
+ // ミリ秒差を 86400000 で割らない。DST を挟むと 23h / 25h の日が出て 1 日ずれる。
221
134
  export function diffCalendarDays(fromMs: number, toMs: number, tz: string): number {
222
135
  const from = dayjs.utc(toDayKey(fromMs, tz), 'YYYYMMDD', true);
223
136
  const to = dayjs.utc(toDayKey(toMs, tz), 'YYYYMMDD', true);
224
137
  return to.diff(from, 'day');
225
138
  }
226
139
 
227
- /**
228
- * [startMs, endMs] と交差する tz 暦年キーを昇順(inclusive)で列挙する。
229
- * `startMs > endMs` なら空配列。
230
- */
231
140
  export function enumerateYearKeys(startMs: number, endMs: number, tz: string): YearKey[] {
232
141
  assertFiniteMs(startMs, 'startMs');
233
142
  assertFiniteMs(endMs, 'endMs');
@@ -240,19 +149,11 @@ export function enumerateYearKeys(startMs: number, endMs: number, tz: string): Y
240
149
  return keys;
241
150
  }
242
151
 
243
- /**
244
- * その暦日キーが nowMs 時点で**完了しているか**(= nowMs が属する暦日より前か)。
245
- * 進行中の暦日・未来の暦日は false。形式不正も false。
246
- */
247
152
  export function isDayKeyCompleted(key: string, nowMs: number, tz: string): boolean {
248
153
  if (!isDayKeyFormat(key)) return false;
249
154
  return key < toDayKey(nowMs, tz);
250
155
  }
251
156
 
252
- /**
253
- * 直近 count 個の完了済み tz 暦日キーを新しい順で返す。
254
- * nowMs が属する進行中の暦日は含めない。count <= 0 / 非数値は空配列。
255
- */
256
157
  export function recentCompletedDayKeys(count: number, nowMs: number, tz: string): DayKey[] {
257
158
  const wanted = Math.max(0, Math.floor(count));
258
159
  if (!(wanted > 0)) return [];