Skip to main content

ccxt_base/
value.rs

1// Native Rust – hand-written Value type.
2//
3// The ast-transpiler emits `Value::Map(...)`, `Value::Str(...)`, etc.
4// This module defines those variants so generated code compiles without
5// requiring serde_json macros in every file.
6//
7// At the HTTP boundary (exchange.rs) we convert between Value and
8// serde_json::Value for serialisation / deserialisation.
9
10// Value::Map uses `IndexMap` (re-exported here as `HashMap` so the rest
11// of the codebase — including transpiler-emitted `std::collections::
12// HashMap::new()` calls swapped to `indexmap::IndexMap::new()` by a
13// post-pass — keeps building literals via the same API). Insertion
14// order matters for JSON / URL-encoded payloads: exchanges like bingx /
15// digifinex / mexc reject (and the static request fixtures assert)
16// specific key orders such as `{symbol,type,side,quantity,price}`.
17pub use indexmap::IndexMap as HashMap;
18use std::borrow::Cow;
19use std::sync::Arc;
20#[cfg(feature = "transpiled-base")]
21use crate::exchange_generated::ExchangeBase;
22
23/// A dynamic value type that mirrors the CCXT JavaScript Value semantics.
24///
25/// `Dict`/`Arr` hold their containers behind an `Arc` so that `clone()` is
26/// an O(1) refcount bump instead of a deep copy — the transpiled parsers
27/// and the static-test assertions clone Values pervasively (every
28/// `safeString`/`safeNumber`, every recursion level), which dominated
29/// runtime. Mutation goes through `Arc::make_mut` (copy-on-write): it
30/// only deep-copies when the container is actually shared.
31///
32/// NOTE: the variants are named `Dict`/`Arr`, but construction uses the
33/// associated functions `Value::Map(..)` / `Value::Array(..)` /
34/// `Value::List(..)` (which wrap the `Arc`) so the ~18k transpiler-emitted
35/// `Value::Map({..})` / `Value::List(vec![..])` call sites need no change.
36/// Pattern matches use `Value::Dict(..)` / `Value::Arr(..)`.
37/// `Str` holds a `Cow<'static, str>`: transpiler-emitted string literals
38/// borrow their `&'static str` (`Value::Str("lit".into())`, zero allocation)
39/// while runtime-built strings stay owned. `clone()` on a borrowed literal
40/// is a pointer copy.
41#[derive(Debug, Clone, PartialEq)]
42pub enum Value {
43    Null,
44    Bool(bool),
45    Int(i64),
46    Float(f64),
47    Str(Cow<'static, str>),
48    Dict(Arc<HashMap<String, Value>>),
49    Arr(Arc<Vec<Value>>),
50}
51
52impl Default for Value {
53    fn default() -> Self {
54        Value::Null
55    }
56}
57
58impl Value {
59    /// Mirrors TS `Precise.reduce()`: when this Value is a
60    /// `Precise::new(...)` Map (carries the `__precise` marker), strip
61    /// trailing zeros from `integer` and bump `decimals` down to match.
62    /// Used by phemex's `to_en` after it shifts `decimals` by the
63    /// market's `valueScale`: subtracts decimals, then reduce balances
64    /// the integer side so the final `stringify_param` renders the
65    /// scaled integer correctly (`0.1` × 10^8 → `10000000`).
66    pub fn reduce(&mut self) {
67        let m = match self { Value::Dict(m) if m.contains_key("__precise") => Arc::make_mut(m), _ => return };
68        let mut decimals: i64 = match m.get("decimals") {
69            Some(Value::Int(n)) => *n,
70            _ => return,
71        };
72        let mut integer: String = match m.get("integer") {
73            Some(Value::Str(s)) => s.to_string(),
74            _ => return,
75        };
76        // Negative decimals → pad zeros onto the integer.
77        if decimals < 0 {
78            // careful: a leading '-' (negative number) stays at the front.
79            let (sign, digits) = if let Some(rest) = integer.strip_prefix('-') {
80                ("-", rest.to_string())
81            } else { ("", integer.clone()) };
82            let padded = format!("{digits}{:0<width$}", "", width = (-decimals) as usize);
83            integer = format!("{sign}{padded}");
84            decimals = 0;
85        }
86        // Trim trailing zeros while there are decimal places to consume.
87        while decimals > 0 && integer.ends_with('0') && integer.len() > 1 {
88            integer.pop();
89            decimals -= 1;
90        }
91        m.insert("integer".to_string(),  Value::Str(Cow::Owned(integer)));
92        m.insert("decimals".to_string(), Value::Int(decimals));
93    }
94
95    /// `append(item)` on an Array — pushes the item. Mirrors TS
96    /// `array.push` shape (single arg, no return).
97    ///
98    /// On a WS-cache Map (carrying a `__cacheKind` marker; see
99    /// `crate::pro::cache`) it dispatches to the per-kind logic below.
100    pub fn append(&mut self, item: Value) {
101        match self {
102            Value::Arr(a) => Arc::make_mut(a).push(item),
103            Value::Dict(m) if m.contains_key("__cacheKind") => {
104                cache_append(self, item);
105            }
106            _ => {}
107        }
108    }
109
110    /// `clear()` — resets the rolling buffer for a cache marker (or
111    /// truncates the inner array of an `Arr` value).
112    pub fn clear(&mut self) {
113        match self {
114            Value::Arr(a) => Arc::make_mut(a).clear(),
115            Value::Dict(m) if m.contains_key("__cacheKind") => {
116                if let Some(id) = cache_id_of_m(m) {
117                    with_cache_cell(id, |c| {
118                        if let Some(Value::Arr(data)) = c.get_mut("_data") { Arc::make_mut(data).clear(); }
119                        cache_reset_bookkeeping(c);
120                    });
121                } else {
122                    let m = Arc::make_mut(m);
123                    if let Some(Value::Arr(data)) = m.get_mut("_data") {
124                        Arc::make_mut(data).clear();
125                    }
126                    cache_reset_bookkeeping(m);
127                }
128            }
129            _ => {}
130        }
131    }
132
133    /// `getLimit(symbol, limit)` for the cache markers. Returns the
134    /// count of new updates since the last call (clamped by `limit`
135    /// when supplied) and arms the per-symbol / global reset flag so
136    /// the next `append` zeroes the counter.
137    pub fn get_limit(&mut self, symbol: Value, limit: Value) -> Value {
138        if matches!(self, Value::Dict(d) if d.contains_key("__cacheKind")) {
139            cache_get_limit(self, symbol, limit)
140        } else {
141            limit
142        }
143    }
144
145    /// Constructor named to match the ast-transpiler's emission shape:
146    /// `Value::List(vec![...])`. Aliases `Value::Array`. Note that this
147    /// is a function, not a variant — so pattern matches still use
148    /// `Value::Array(_)`, not `Value::List(_)`.
149    #[allow(non_snake_case)]
150    pub fn List(items: Vec<Value>) -> Value {
151        Value::Arr(Arc::new(items))
152    }
153
154    /// Construction shim — the transpiler emits `Value::Map({..IndexMap..})`
155    /// in ~18k places; this wraps the map in the `Arc` the `Dict` variant
156    /// now holds. (An associated fn, not a variant — patterns use `Dict`.)
157    #[allow(non_snake_case)]
158    pub fn Map(m: HashMap<String, Value>) -> Value {
159        Value::Dict(Arc::new(m))
160    }
161
162    /// Construction shim for `Value::Array(vec)` call sites.
163    #[allow(non_snake_case)]
164    pub fn Array(a: Vec<Value>) -> Value {
165        Value::Arr(Arc::new(a))
166    }
167
168    // ── constructors ──────────────────────────────────────────────────────────
169
170    pub fn str(s: impl Into<String>) -> Self {
171        Value::Str(Cow::Owned(s.into()))
172    }
173
174    pub fn int(n: i64) -> Self {
175        Value::Int(n)
176    }
177
178    pub fn float(f: f64) -> Self {
179        Value::Float(f)
180    }
181
182    pub fn bool(b: bool) -> Self {
183        Value::Bool(b)
184    }
185
186    pub fn map(m: HashMap<String, Value>) -> Self {
187        Value::Map(m)
188    }
189
190    pub fn array(a: Vec<Value>) -> Self {
191        Value::Array(a)
192    }
193
194    // ── type checks ───────────────────────────────────────────────────────────
195
196    pub fn is_null(&self)   -> bool { matches!(self, Value::Null) }
197    pub fn is_str(&self)    -> bool { matches!(self, Value::Str(_)) }
198    pub fn is_int(&self)    -> bool { matches!(self, Value::Int(_)) }
199    pub fn is_float(&self)  -> bool { matches!(self, Value::Float(_)) }
200    pub fn is_number(&self) -> bool { matches!(self, Value::Int(_) | Value::Float(_)) }
201    pub fn is_bool(&self)   -> bool { matches!(self, Value::Bool(_)) }
202    pub fn is_map(&self)    -> bool { matches!(self, Value::Dict(_)) }
203    pub fn is_array(&self)  -> bool { matches!(self, Value::Arr(_)) }
204    pub fn is_truthy(&self) -> bool {
205        match self {
206            Value::Null       => false,
207            Value::Bool(b)    => *b,
208            Value::Int(n)     => *n != 0,
209            Value::Float(f)   => *f != 0.0,
210            Value::Str(s)     => !s.is_empty(),
211            Value::Dict(m)    => !m.is_empty(),
212            Value::Arr(a)     => !a.is_empty(),
213        }
214    }
215
216    // ── accessors ─────────────────────────────────────────────────────────────
217
218    pub fn as_str(&self)   -> Option<&str>  { if let Value::Str(s) = self { Some(s.as_ref()) } else { None } }
219    pub fn as_i64(&self)   -> Option<i64>   { if let Value::Int(n) = self { Some(*n) } else { None } }
220    pub fn as_f64(&self)   -> Option<f64> {
221        match self {
222            Value::Float(f) => Some(*f),
223            Value::Int(n)   => Some(*n as f64),
224            _               => None,
225        }
226    }
227    pub fn as_bool(&self)  -> Option<bool>  { if let Value::Bool(b) = self { Some(*b) } else { None } }
228    pub fn as_map(&self)   -> Option<&HashMap<String, Value>> {
229        if let Value::Dict(m) = self { Some(&**m) } else { None }
230    }
231    pub fn as_array(&self) -> Option<&Vec<Value>> {
232        if let Value::Arr(a) = self { Some(&**a) } else { None }
233    }
234
235    /// Length of array, map, or string; 0 for everything else.
236    /// String length counts Unicode chars (matches TS `String#length`
237    /// closely enough for ASCII-only API addresses/identifiers).
238    pub fn len(&self) -> usize {
239        match self {
240            Value::Arr(a)   => a.len(),
241            Value::Dict(m)  => m.len(),
242            Value::Str(s)   => s.chars().count(),
243            _               => 0,
244        }
245    }
246
247    pub fn is_empty(&self) -> bool { self.len() == 0 }
248
249    // ── duck-typed method stubs that transpiled code calls on a Value ────
250    // These exist so transpiled code that calls methods on Value-typed
251    // locals (e.g. `parentRestInstance.describe()`) compiles. They return
252    // `Value::Null` and are placeholders for richer dispatch.
253
254    pub fn describe(&self) -> Value { Value::Null }
255    /// `client.reject(error, messageHash)` — stores a rejection the `watch`
256    /// drive loop delivers to the awaiting caller. Routes by the client
257    /// handle's `url` to the WS registry (no-op on a non-client Value).
258    pub fn reject(&self, args: &[Value]) -> Value {
259        crate::pro::ws_client::value_reject(self, args)
260    }
261    /// `client.resolve(value, messageHash)` — stores the resolved value the
262    /// `watch` drive loop returns. Routes by the client handle's `url`.
263    pub fn resolve(&self, args: &[Value]) -> Value {
264        crate::pro::ws_client::value_resolve(self, args)
265    }
266    /// `client.future(messageHash)` — TS's atomic check-and-insert: opens a
267    /// single-flight for the hash (or joins the open one) and hands back a
268    /// handle. Registering is the whole point — it is what makes a concurrent
269    /// caller's `messageHash in client.futures` test true, so only one of them
270    /// does the work (venue `authenticate` leader election). Await the handle
271    /// with `exchange_stubs::ws_await_flight`; the transpiler emits that
272    /// wherever the TS source awaits.
273    pub fn future(&self, args: &[Value]) -> Value {
274        self.open_flight(args.get(0).cloned().unwrap_or(Value::Null))
275    }
276    /// `client.reusable_future(messageHash)` — shared flight per hash, i.e. the
277    /// same registry and handle as `future`.
278    pub fn reusable_future(&self, msg_hash: Value) -> Value {
279        self.open_flight(msg_hash)
280    }
281    /// Shared body of `future` / `reusable_future`: open-or-join the flight on
282    /// the client this handle names, and return a handle to it. A non-client
283    /// receiver (or a non-string hash) degrades to the old pass-the-hash-back
284    /// behaviour so unrelated transpiled code keeps compiling.
285    fn open_flight(&self, msg_hash: Value) -> Value {
286        let hash = match &msg_hash {
287            Value::Str(h) => h.clone(),
288            _ => return msg_hash,
289        };
290        match crate::pro::ws_client::url_of(self) {
291            Some(url) => {
292                let led = crate::pro::ws_client::begin_flight(&url, &hash);
293                crate::pro::ws_client::flight_handle(&url, &hash, led)
294            }
295            None => msg_hash,
296        }
297    }
298    /// Field accessor: `cache.hashmap` — same as the WS Cache marker's
299    /// hashmap sub-dict. Some transpiled WS code reads this directly
300    /// via the JS field-access syntax rather than going through
301    /// `get_value`.
302    pub fn hashmap(&self) -> Value {
303        if let Value::Dict(d) = self {
304            // Cache marker: the live hashmap lives in the shared CACHE_STORE
305            // (keyed by __cache_id), not on the marker Dict. Return a copy with
306            // each symbol bucket tagged with a `__cache_backref` so that a
307            // transpiled write-back like `cache.hashmap[symbol][id] = order`
308            // (the JS reference write) persists through to the store — see
309            // try_cache_hashmap_write.
310            if let Some(id) = cache_id_of(self) {
311                let hm = with_cache_cell(id, |m| m.get("hashmap").cloned().unwrap_or(Value::Null));
312                return tag_cache_hashmap_buckets(hm, id);
313            }
314            if let Some(v) = d.get("hashmap") { return v.clone(); }
315        }
316        Value::Null
317    }
318    /// `client.send(payload)` — queues a frame on the WS connection (routed by
319    /// the client handle's `url`). No-op on a non-client Value.
320    pub fn send(&self, args: &[Value]) -> Value {
321        crate::pro::ws_client::value_send(self, args)
322    }
323    /// `client.decode_proto_msg(...)` — exchange-specific protobuf
324    /// decode helper; stubbed to `Value::Null`.
325    pub fn decode_proto_msg(&self, _args: &[Value]) -> Value { Value::Null }
326    /// `client.on_pong(...)` — WS heartbeat hook; records the pong time.
327    pub fn on_pong(&self, _args: &[Value]) -> Value {
328        crate::pro::ws_client::value_on_pong(self)
329    }
330    /// WS stub — transpiled `fn(...args)` over a Value-typed callable.
331    pub fn call(&self, _args: &[Value]) -> Value { Value::Null }
332    /// `exchange.isDictionary(value)` — transpiled tests treat `exchange`
333    /// as `Value` instead of the typed `Exchange`, so we mirror the
334    /// dict-typecheck method here.
335    pub fn is_dictionary(&self, value: Value) -> Value {
336        Value::Bool(matches!(value, Value::Dict(_)))
337    }
338    /// Lifts this snapshot's `options` + `currencies` onto a throwaway base
339    /// `Exchange` so the *transpiled* conversion methods can run against it.
340    /// The afterConstruct test transpiles its call sites with `exchange:
341    /// Value`, so these methods have to exist on `Value` — but the logic
342    /// must stay in the transpiled base, not be duplicated here.
343    #[cfg(feature = "transpiled-base")]
344    fn snapshot_as_exchange(&self) -> crate::exchange::Exchange {
345        let mut ex = crate::exchange::Exchange::new(None);
346        ex.options = crate::runtime::get_value(self, &Value::Str("options".into()));
347        ex.currencies = crate::runtime::get_value(self, &Value::Str("currencies".into()));
348        ex
349    }
350
351    /// `exchange.networkCodeToId(code, currency)` on a snapshot `Value` —
352    /// delegates to the transpiled `Exchange::network_code_to_id`.
353    pub fn network_code_to_id(&self, code: Value, args: &[Value]) -> Value {
354        #[cfg(feature = "transpiled-base")]
355        {
356            let currency = args.first().cloned().unwrap_or(Value::Null);
357            return crate::exchange::BaseCore::new(self.snapshot_as_exchange()).network_code_to_id(code, &[currency]);
358        }
359        #[cfg(not(feature = "transpiled-base"))]
360        {
361            let _ = args;
362            code
363        }
364    }
365
366    /// `exchange.networkIdToCode(networkId, currency)` on a snapshot `Value`
367    /// — delegates to the transpiled `Exchange::network_id_to_code`.
368    pub fn network_id_to_code(&self, args: &[Value]) -> Value {
369        #[cfg(feature = "transpiled-base")]
370        {
371            return crate::exchange::BaseCore::new(self.snapshot_as_exchange()).network_id_to_code(args);
372        }
373        #[cfg(not(feature = "transpiled-base"))]
374        {
375            let _ = args;
376            Value::Null
377        }
378    }
379
380    /// `exchange.extend(a, b, ...)` on a snapshot `Value` — CCXT's shallow
381    /// object merge. Pure (ignores exchange state), so it delegates to the
382    /// transpiled `Exchange::extend`. Used by the (prediction-aware) transpiled
383    /// test harness, where `exchange` is a dynamic `Value` handle.
384    pub fn extend(&self, a: Value, args: &[Value]) -> Value {
385        #[cfg(feature = "transpiled-base")]
386        {
387            return self.snapshot_as_exchange().extend(a, args);
388        }
389        #[cfg(not(feature = "transpiled-base"))]
390        {
391            let _ = args;
392            a
393        }
394    }
395
396    /// `exchange.setMarkets(markets)` on a snapshot `Value` — used by the
397    /// prediction test harness to seed event-derived markets. Delegates the
398    /// indexing to the transpiled `Exchange::set_markets`, then writes the
399    /// computed `markets`/`markets_by_id`/`symbols` back onto the `Value`
400    /// handle so later `get_value(exchange, "markets")` reads see them.
401    pub fn set_markets(&mut self, markets: Value) -> Value {
402        #[cfg(feature = "transpiled-base")]
403        {
404            // If this snapshot is backed by a live Core (`__live_id`), route to
405            // it so the Core's own `set_markets` runs — for a prediction venue
406            // that's `PredictionExchange::set_markets` (outcome→symbol aliasing +
407            // populateOutcomes), populating the outcome caches on the very
408            // instance the method dispatch uses. Without this, the prediction
409            // static request tests seed markets onto a throwaway snapshot and the
410            // live Core resolves every outcome by (re)fetching events.
411            if let Value::Dict(m) = &*self {
412                if let Some(Value::Str(id)) = m.get("__live_id") {
413                    if let Some(cb) = live_set_markets_get() {
414                        return cb(&id.clone(), markets);
415                    }
416                }
417            }
418            let mut ex = crate::exchange::BaseCore::new(self.snapshot_as_exchange());
419            let result = ex.set_markets(markets, &[]);
420            crate::runtime::add_element_to_object(self, &Value::Str("markets".into()), ex.markets.clone());
421            crate::runtime::add_element_to_object(self, &Value::Str("markets_by_id".into()), ex.markets_by_id.clone());
422            crate::runtime::add_element_to_object(self, &Value::Str("symbols".into()), ex.symbols.clone());
423            return result;
424        }
425        #[cfg(not(feature = "transpiled-base"))]
426        {
427            let _ = markets;
428            Value::Null
429        }
430    }
431    /// `side.storeArray(delta)` — insert/update/delete by price (or
432    /// by id for the indexed variant). Defined here (rather than next
433    /// to `store`) so that derived exchange code which calls
434    /// `Value::store_array` on a non-side Value still compiles as a
435    /// no-op.
436    pub fn store_array(&mut self, delta: Value) {
437        if side_kind(self).is_some() { side_store_array(self, delta); }
438    }
439    pub fn append_to_array(&self, _v: Value) {}
440
441    // ── conversion to / from serde_json ───────────────────────────────────────
442
443    pub fn to_json(&self) -> serde_json::Value {
444        match self {
445            Value::Null        => serde_json::Value::Null,
446            Value::Bool(b)     => serde_json::Value::Bool(*b),
447            Value::Int(n)      => serde_json::json!(*n),
448            Value::Float(f)    => serde_json::json!(*f),
449            Value::Str(s)      => serde_json::Value::String(s.to_string()),
450            Value::Arr(a)      => serde_json::Value::Array(a.iter().map(Value::to_json).collect()),
451            Value::Dict(m)     => {
452                // A side marker keeps its entries in the shared side store —
453                // serialize as the plain `[[price, amount], …]` array (CCXT's
454                // orderbook.bids/asks shape), matching jsonStringify(orderbook)
455                // in the other languages rather than exposing the internal side
456                // struct. The WS deep-compare unwraps markers itself, so it's
457                // unaffected.
458                if m.contains_key("__side_id") {
459                    let entries = side_entries_view(m);
460                    return serde_json::Value::Array(entries.iter().map(Value::to_json).collect());
461                }
462                // A shared book keeps its scalar meta (nonce/timestamp/…) in the
463                // book store and tags itself with internal markers — drop the
464                // markers and surface the meta so the serialized book is the
465                // clean { bids, asks, timestamp, datetime, nonce, symbol } form.
466                let is_book = m.contains_key("__book_id") || m.contains_key("__bookKind");
467                let mut obj = serde_json::Map::new();
468                for (k, v) in m.iter() {
469                    if is_book && matches!(k.as_str(), "__bookKind" | "__book_id" | "_depth") {
470                        continue;
471                    }
472                    obj.insert(k.clone(), v.to_json());
473                }
474                if let Some(Value::Int(id)) = m.get("__book_id") {
475                    for (k, v) in book_meta_snapshot(*id) { obj.insert(k, v.to_json()); }
476                }
477                // A cache marker keeps its rolling buffer in the shared cache
478                // store — surface it under `_data` for serialization.
479                if m.contains_key("__cacheKind") {
480                    let data = cache_data_snapshot(m);
481                    obj.insert("_data".to_string(),
482                        serde_json::Value::Array(data.iter().map(Value::to_json).collect()));
483                }
484                serde_json::Value::Object(obj)
485            }
486        }
487    }
488
489    pub fn from_json(v: &serde_json::Value) -> Self {
490        match v {
491            serde_json::Value::Null        => Value::Null,
492            serde_json::Value::Bool(b)     => Value::Bool(*b),
493            serde_json::Value::Number(n)   => {
494                if let Some(i) = n.as_i64()  {
495                    Value::Int(i)
496                } else if n.is_u64() {
497                    // Integer in (i64::MAX, u64::MAX] — a large order/trade/
498                    // account id. `Value::Int` is i64 and `f64` would round it,
499                    // so preserve the exact digits as a string (Go does the
500                    // same). CCXT's safe_integer/safe_number read it back as a
501                    // number when needed.
502                    Value::Str(n.to_string().into())
503                } else if let Some(f) = n.as_f64() {
504                    Value::Float(f)
505                } else {
506                    Value::Null
507                }
508            }
509            serde_json::Value::String(s)   => Value::Str(s.clone().into()),
510            serde_json::Value::Array(a)    => Value::Array(a.iter().map(Value::from_json).collect()),
511            serde_json::Value::Object(m)   => Value::Map(
512                m.iter().map(|(k, v)| (k.clone(), Value::from_json(v))).collect()
513            ),
514        }
515    }
516}
517
518impl std::fmt::Display for Value {
519    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
520        match self {
521            Value::Null        => write!(f, "null"),
522            Value::Bool(b)     => write!(f, "{b}"),
523            Value::Int(n)      => write!(f, "{n}"),
524            Value::Float(fl)   => write!(f, "{fl}"),
525            Value::Str(s)      => write!(f, "{s}"),
526            Value::Arr(a)      => write!(f, "[{} items]", a.len()),
527            Value::Dict(m)     => write!(f, "{{{}  keys}}", m.len()),
528        }
529    }
530}
531
532// ── From / Into conversions ───────────────────────────────────────────────────
533
534// Operator overloads so transpiled code's `!x`, `x && y`, `x || y` over
535// Value compile. They follow JS-style truthiness on the Value, not value
536// equality. Result type is `Value::Bool`.
537
538impl std::ops::Not for Value {
539    type Output = Value;
540    fn not(self) -> Value { Value::Bool(!self.is_truthy()) }
541}
542
543impl std::ops::Not for &Value {
544    type Output = Value;
545    fn not(self) -> Value { Value::Bool(!self.is_truthy()) }
546}
547
548impl std::ops::BitAnd for Value {
549    type Output = Value;
550    fn bitand(self, rhs: Value) -> Value {
551        Value::Bool(self.is_truthy() && rhs.is_truthy())
552    }
553}
554
555impl std::ops::BitOr for Value {
556    type Output = Value;
557    fn bitor(self, rhs: Value) -> Value {
558        Value::Bool(self.is_truthy() || rhs.is_truthy())
559    }
560}
561
562impl From<&str>    for Value { fn from(s: &str)   -> Self { Value::Str(Cow::Owned(s.to_owned())) } }
563impl From<String>  for Value { fn from(s: String) -> Self { Value::Str(Cow::Owned(s)) } }
564impl From<i64>     for Value { fn from(n: i64)    -> Self { Value::Int(n) } }
565impl From<f64>     for Value { fn from(f: f64)    -> Self { Value::Float(f) } }
566impl From<bool>    for Value { fn from(b: bool)   -> Self { Value::Bool(b) } }
567/// `From<ExchangeError>` makes `error.clone()` flow into `&[Value]`
568/// slices without an explicit conversion — surfaces the typed error
569/// as a `[Kind] message`-shaped string Value, matching how
570/// `runtime::panic_msg_to_error` round-trips it back into a typed
571/// `ExchangeError` for the caller.
572impl From<crate::ExchangeError> for Value {
573    fn from(e: crate::ExchangeError) -> Self {
574        Value::Str(format!("[{}] {}", e.kind, e.message).into())
575    }
576}
577impl From<HashMap<String, Value>> for Value {
578    fn from(m: HashMap<String, Value>) -> Self { Value::Map(m) }
579}
580impl From<Vec<Value>> for Value {
581    fn from(a: Vec<Value>) -> Self { Value::Array(a) }
582}
583impl From<serde_json::Value> for Value {
584    fn from(v: serde_json::Value) -> Self { Value::from_json(&v) }
585}
586
587// ── Helper free-functions (generated code calls these) ────────────────────────
588
589/// Optional live-snapshot accessor. Installed by `ccxt_tests::live_dispatch`
590/// so reads of the heavy fields (`markets`, `markets_by_id`, `symbols`, …)
591/// on the test-runner's snapshot don't deep-clone the entire ~4k-entry
592/// markets Map on every helper invocation. When `get_value` sees a Map
593/// carrying `__live_id`, it consults this callback to resolve the key
594/// directly from the cached real `<Id>Core`. Production / non-test code
595/// leaves the callback unset and falls through to the normal map lookup.
596type LiveLookupFn = fn(id: &str, key: &str) -> Option<Value>;
597// Plain atomic-load-style global — `tokio::main` spawns worker threads
598// that wouldn't see a `thread_local!` value set in main, so the lookup
599// has to be shared across all threads. Stored as a usize because
600// `AtomicPtr<fn>` is awkward to express. `fn` pointers are always
601// non-null when set; 0 means "not installed".
602static LIVE_LOOKUP_PTR: std::sync::atomic::AtomicUsize =
603    std::sync::atomic::AtomicUsize::new(0);
604
605pub fn set_live_lookup(f: LiveLookupFn) {
606    LIVE_LOOKUP_PTR.store(f as usize, std::sync::atomic::Ordering::Release);
607}
608
609fn live_lookup_get() -> Option<LiveLookupFn> {
610    let n = LIVE_LOOKUP_PTR.load(std::sync::atomic::Ordering::Acquire);
611    if n == 0 { None } else {
612        // SAFETY: only ever stored as `fn(&str, &str) -> Option<Value>`
613        // via `set_live_lookup`; the pointer-to-fn round-trip is sound.
614        Some(unsafe { std::mem::transmute::<usize, LiveLookupFn>(n) })
615    }
616}
617
618// Companion to `LiveLookupFn` but for writing: routes `exchange.setMarkets(...)`
619// on a `__live_id` snapshot to the registered *live* Core, so the Core's
620// `PredictionExchange::set_markets` override (outcome aliasing + populateOutcomes)
621// runs against the real instance the method dispatch will use. Returns the
622// resulting markets. See `Value::set_markets`.
623type LiveSetMarketsFn = fn(id: &str, markets: Value) -> Value;
624static LIVE_SET_MARKETS_PTR: std::sync::atomic::AtomicUsize =
625    std::sync::atomic::AtomicUsize::new(0);
626
627pub fn set_live_set_markets(f: LiveSetMarketsFn) {
628    LIVE_SET_MARKETS_PTR.store(f as usize, std::sync::atomic::Ordering::Release);
629}
630
631fn live_set_markets_get() -> Option<LiveSetMarketsFn> {
632    let n = LIVE_SET_MARKETS_PTR.load(std::sync::atomic::Ordering::Acquire);
633    if n == 0 { None } else {
634        // SAFETY: only ever stored as `fn(&str, Value) -> Value` via
635        // `set_live_set_markets`; the pointer-to-fn round-trip is sound.
636        Some(unsafe { std::mem::transmute::<usize, LiveSetMarketsFn>(n) })
637    }
638}
639
640/// Hot-path `get_value` variant that takes the key as a `&str` directly,
641/// skipping a `Value::Str` heap allocation. Used by the `safe_*_k`
642/// fast-path readers the transpiler routes literal-key calls through.
643#[inline]
644pub fn get_value_k(obj: &Value, key: &str) -> Value {
645    if let Value::Dict(m) = obj {
646        // A shared order book keeps its scalar meta (nonce/timestamp/…) in the
647        // book store; route those through it so the safe_* helpers (which go via
648        // get_value_k) see the shared value, not the empty Dict slot.
649        if is_book_meta_key(key) {
650            if let Some(id) = book_id_of(m) { return book_meta_get(id, key); }
651        }
652        if key == "cache" {
653            if let Some(id) = book_id_of(m) { return book_cache_handle(id); }
654        }
655        if let Some(v) = m.get(key) {
656            if !matches!(v, Value::Null) {
657                return v.clone();
658            }
659        }
660        if let Some(id_val) = m.get("__live_id") {
661            if let (Value::Str(id), Some(cb)) = (id_val, live_lookup_get()) {
662                if let Some(v) = cb(id, key) { return v; }
663            }
664        }
665    }
666    Value::Null
667}
668
669/// Access a value in a map by string key, or array by integer key encoded as
670/// a `Value::Str` / `Value::Int`. Returns `Value::Null` on miss.
671pub fn get_value(obj: &Value, key: &Value) -> Value {
672    // Cache / order-book / side markers expose numeric indexing as if
673    // they were arrays — `cache[i]` reads `_data[i]`, `side[i]` reads
674    // `_entries[i]`. Handle this before the regular dict lookup so the
675    // transpiled `get_value(&cache, &Value::Int(0))` calls reach the
676    // right backing buffer.
677    // The index may arrive as an Int (`get_value(&side, &Value::Int(0))`) or as
678    // a numeric string — the `safe_*` helpers stringify their key, so
679    // `safe_value(cache, 0)` reaches here as `Str("0")`. Accept both.
680    if let Value::Dict(m) = obj {
681        let idx = match key {
682            Value::Int(i) if *i >= 0 => Some(*i as usize),
683            Value::Str(s) => s.parse::<usize>().ok(),
684            _ => None,
685        };
686        if let Some(i) = idx {
687            if let Some(id) = book_cache_id_of(m) {
688                return book_cache_at(id, i);
689            }
690            if m.contains_key("__cacheKind") {
691                return cache_at(m, i);
692            }
693            if m.contains_key("__sideKind") {
694                return side_entry_at(m, i);
695            }
696        }
697    }
698    match (obj, key) {
699        (Value::Dict(m), Value::Str(k)) => {
700            // A shared order book keeps its scalar meta (nonce/timestamp/…) in
701            // the book store so mutations propagate across clones.
702            if is_book_meta_key(k) {
703                if let Some(id) = book_id_of(m) { return book_meta_get(id, k); }
704            }
705            if k == "cache" {
706                if let Some(id) = book_id_of(m) { return book_cache_handle(id); }
707            }
708            // A cache marker's `hashmap` (bucket index) lives in the shared
709            // CACHE_STORE cell, not the marker Dict — route the read there so a
710            // transpiled `cache.hashmap` sees live bucket state (the base-ws
711            // eviction test counts `Object.keys(cache.hashmap)`).
712            if k == "hashmap" && m.contains_key("__cacheKind") {
713                if let Some(id) = cache_id_of_m(m) {
714                    return with_cache_cell(id, |c| c.get("hashmap").cloned().unwrap_or(Value::Null));
715                }
716                return m.get("hashmap").cloned().unwrap_or(Value::Null);
717            }
718            // A client handle (`Map{url, subscriptions, futures}`) serves its
719            // subscriptions/futures live from the WS registry, so a read after a
720            // write (upbit sets subs then reads them back to build its subscribe
721            // frame) is coherent rather than a stale embedded snapshot.
722            if (k == "subscriptions" || k == "futures")
723                && m.contains_key("subscriptions") && m.contains_key("futures")
724            {
725                if let Some(Value::Str(url)) = m.get("url") {
726                    return crate::pro::ws_client::client_field_live(url, k);
727                }
728            }
729            // Snapshot value wins WHEN PRESENT AND NON-NULL. Tests that
730            // mutate `exchange.options` (e.g. kucoin broker-id test) need
731            // the snapshot view to take precedence; but `to_value`
732            // pre-populates heavy fields like `markets` with `Null`
733            // before `load_markets` runs, so we still need to fall back
734            // to the live-lookup if the snapshot value is null.
735            let snapshot_val = m.get(k.as_ref());
736            if let Some(v) = snapshot_val {
737                if !matches!(v, Value::Null) {
738                    return v.clone();
739                }
740            }
741            if let Some(id_val) = m.get("__live_id") {
742                if let (Value::Str(id), Some(cb)) = (id_val, live_lookup_get()) {
743                    if let Some(v) = cb(id, k) { return v; }
744                }
745            }
746            Value::Null
747        }
748        (Value::Arr(a), Value::Int(i)) => a.get(*i as usize).cloned().unwrap_or(Value::Null),
749        (Value::Arr(a), Value::Str(k)) => {
750            if let Ok(i) = k.parse::<usize>() {
751                a.get(i).cloned().unwrap_or(Value::Null)
752            } else {
753                Value::Null
754            }
755        }
756        // JS string indexing: `s[i]` returns the i-th character as a
757        // 1-char string (e.g. bitfinex `amountString[0] === '-'` to detect
758        // a negative). Char-based so multi-byte UTF-8 is handled.
759        (Value::Str(s), Value::Int(i)) => {
760            if *i < 0 {
761                return Value::Null;
762            }
763            match s.chars().nth(*i as usize) {
764                Some(c) => Value::Str(c.to_string().into()),
765                None    => Value::Null,
766            }
767        }
768        _ => Value::Null,
769    }
770}
771
772/// Set a key/index in a map or array value.
773pub fn set_value(obj: &mut Value, key: &Value, val: Value) {
774    match (obj, key) {
775        (Value::Dict(m), Value::Str(k)) => {
776            if try_book_meta_write(m, k, &val) { return; }
777            // Persist to the live client AND keep the local snapshot coherent so
778            // code that reads back what it just wrote (upbit builds its subscribe
779            // frame from `object_keys(client.subscriptions)`) sees the new entry.
780            try_ws_subs_write(m, k, &val);
781            try_ws_sub_field_write(m, k, &val);
782            Arc::make_mut(m).insert(k.to_string(), val);
783        }
784        (Value::Arr(a), Value::Int(i)) => {
785            let idx = *i as usize;
786            let a = Arc::make_mut(a);
787            if idx < a.len() { a[idx] = val; }
788        }
789        _ => {}
790    }
791}
792
793// ── safeXxx helpers (mirrors Exchange.ts safe helpers) ─────────────────────
794
795pub fn safe_string(obj: &Value, key: &str, default: Option<&str>) -> Option<String> {
796    let v = get_value(obj, &Value::Str(key.to_owned().into()));
797    match v {
798        Value::Str(s)  => Some(s.to_string()),
799        Value::Int(n)  => Some(n.to_string()),
800        Value::Float(f)=> Some(f.to_string()),
801        // Booleans are not strings/finite numbers → TS `safeString` returns the
802        // default for them (not "true"/"false"), same as lists/dicts.
803        Value::Null    => default.map(str::to_owned),
804        _              => default.map(str::to_owned),
805    }
806}
807
808pub fn safe_number(obj: &Value, key: &str, default: Option<f64>) -> Option<f64> {
809    let v = get_value(obj, &Value::Str(key.to_owned().into()));
810    match v {
811        Value::Float(f) => Some(f),
812        Value::Int(n)   => Some(n as f64),
813        Value::Str(s)   => s.parse::<f64>().ok().or(default),
814        _               => default,
815    }
816}
817
818pub fn safe_integer(obj: &Value, key: &str, default: Option<i64>) -> Option<i64> {
819    let v = get_value(obj, &Value::Str(key.to_owned().into()));
820    match v {
821        Value::Int(n)   => Some(n),
822        Value::Float(f) => Some(f as i64),
823        Value::Str(s)   => s.parse::<i64>().ok().or(default),
824        _               => default,
825    }
826}
827
828pub fn safe_bool(obj: &Value, key: &str, default: Option<bool>) -> Option<bool> {
829    let v = get_value(obj, &Value::Str(key.to_owned().into()));
830    match v {
831        Value::Bool(b)  => Some(b),
832        Value::Int(n)   => Some(n != 0),
833        Value::Str(s)   => match s.to_lowercase().as_str() {
834            "true" | "1" | "yes" => Some(true),
835            "false"| "0" | "no"  => Some(false),
836            _                    => default,
837        },
838        _               => default,
839    }
840}
841
842/// Recursively merges `src` into `dst`.
843/// For map/map overlaps the source fields win (deep extend).
844pub fn deep_extend(dst: Value, src: Value) -> Value {
845    match (dst, src) {
846        (Value::Dict(mut d), Value::Dict(s)) => {
847            let dm = Arc::make_mut(&mut d);
848            let sm = Arc::try_unwrap(s).unwrap_or_else(|arc| (*arc).clone());
849            for (k, v) in sm {
850                let entry = dm.shift_remove(&k).unwrap_or(Value::Null);
851                dm.insert(k, deep_extend(entry, v));
852            }
853            Value::Dict(d)
854        }
855        (_, src) => src,
856    }
857}
858
859// ────────────────────────────────────────────────────────────────────────────
860// WS cache helpers — operate on the `Value::Dict` marker maps produced by
861// `crate::pro::cache`. Logic mirrors `ts/src/base/ws/Cache.ts`.
862// ────────────────────────────────────────────────────────────────────────────
863
864fn cache_str_field(item: &Value, key: &str) -> Option<String> {
865    match item {
866        Value::Dict(d) => match d.get(key) {
867            // Coerce to the string the TS uses as an object key: exchanges send
868            // integer order ids, and JS `byId[1]` / `byId["1"]` are the same slot,
869            // so a numeric id must dedupe like its string form (else the bucket
870            // lookup and the _data removal disagree and a duplicate row leaks).
871            Some(Value::Str(s)) => Some(s.to_string()),
872            Some(Value::Int(n)) => Some(n.to_string()),
873            Some(Value::Float(f)) => Some(f.to_string()),
874            Some(Value::Bool(b)) => Some(b.to_string()),
875            _ => None,
876        },
877        _ => None,
878    }
879}
880
881/// Tag every symbol bucket of a cache hashmap copy with a `__cache_backref`
882/// = [cache_id, symbol] so a later `bucket[id] = order` write can be routed
883/// back into the shared CACHE_STORE (see `try_cache_hashmap_write`). Mirrors
884/// the JS reference semantics where `cache.hashmap[symbol]` is the live row.
885fn tag_cache_hashmap_buckets(hm: Value, id: i64) -> Value {
886    if let Value::Dict(d) = &hm {
887        let mut out: HashMap<String, Value> = HashMap::new();
888        for (sym, bucket) in d.iter() {
889            if let Value::Dict(bd) = bucket {
890                let mut nb: HashMap<String, Value> = (**bd).clone();
891                nb.insert(
892                    "__cache_backref".to_string(),
893                    Value::Arr(std::sync::Arc::new(vec![Value::Int(id), Value::Str(sym.clone().into())])),
894                );
895                out.insert(sym.clone(), Value::Dict(std::sync::Arc::new(nb)));
896            } else {
897                out.insert(sym.clone(), bucket.clone());
898            }
899        }
900        return Value::Dict(std::sync::Arc::new(out));
901    }
902    hm
903}
904
905/// When a transpiled `bucket[key] = item` write lands on a cache-hashmap bucket
906/// tagged by `tag_cache_hashmap_buckets`, persist `item` into the shared
907/// CACHE_STORE: update `hashmap[symbol][key]` and the matching `_data` row.
908/// This is how cross-handler mutations of a cached order (fee/trades
909/// accumulation in handleMyTrade, later read by handleOrder) survive Rust's
910/// copy-on-write `Value` semantics. Returns true if a write-through happened.
911pub(crate) fn try_cache_hashmap_write(bucket: &HashMap<String, Value>, key: &str, item: &Value) -> bool {
912    let (id, sym) = match bucket.get("__cache_backref") {
913        Some(Value::Arr(a)) => match (a.first(), a.get(1)) {
914            (Some(Value::Int(id)), Some(Value::Str(s))) => (*id, s.clone()),
915            _ => return false,
916        },
917        _ => return false,
918    };
919    with_cache_cell(id, |m| {
920        // hashmap[sym][key] = item
921        {
922            let hm = cache_dict_field_mut(m, "hashmap");
923            let b = hm.entry(sym.to_string()).or_insert_with(|| Value::Map(HashMap::new()));
924            if let Value::Dict(bd) = b {
925                Arc::make_mut(bd).insert(key.to_string(), item.clone());
926            }
927        }
928        // update the matching _data row (matched by symbol + id/side == key)
929        let data = cache_data_mut(m);
930        for x in data.iter_mut() {
931            if cache_str_field(x, "symbol").as_deref() == Some(&sym)
932                && (cache_str_field(x, "id").as_deref() == Some(key)
933                    || cache_str_field(x, "side").as_deref() == Some(key))
934            {
935                *x = item.clone();
936                break;
937            }
938        }
939    });
940    true
941}
942
943fn cache_kind(v: &Value) -> Option<String> {
944    match v {
945        Value::Dict(d) => match d.get("__cacheKind") {
946            Some(Value::Str(s)) => Some(s.to_string()),
947            _ => None,
948        },
949        _ => None,
950    }
951}
952
953fn cache_max_size(v: &Value) -> Option<usize> {
954    match v {
955        Value::Dict(d) => match d.get("maxSize") {
956            Some(Value::Int(n)) if *n > 0 => Some(*n as usize),
957            _ => None,
958        },
959        _ => None,
960    }
961}
962
963/// `_data` is the rolling buffer Vec for every cache kind. Returns a
964/// mutable handle to the inner Vec by going through `Arc::make_mut`.
965fn cache_data_mut(m: &mut HashMap<String, Value>) -> &mut Vec<Value> {
966    let entry = m.entry("_data".to_string()).or_insert_with(|| Value::Array(Vec::new()));
967    if let Value::Arr(a) = entry {
968        return Arc::make_mut(a);
969    }
970    *entry = Value::Array(Vec::new());
971    if let Value::Arr(a) = entry {
972        return Arc::make_mut(a);
973    }
974    unreachable!()
975}
976
977fn cache_dict_field_mut<'a>(m: &'a mut HashMap<String, Value>, key: &str) -> &'a mut HashMap<String, Value> {
978    let entry = m.entry(key.to_string()).or_insert_with(|| Value::Map(HashMap::new()));
979    if let Value::Dict(d) = entry {
980        return Arc::make_mut(d);
981    }
982    *entry = Value::Map(HashMap::new());
983    if let Value::Dict(d) = entry {
984        return Arc::make_mut(d);
985    }
986    unreachable!()
987}
988
989fn cache_int_field(m: &HashMap<String, Value>, key: &str) -> i64 {
990    match m.get(key) { Some(Value::Int(n)) => *n, _ => 0 }
991}
992
993fn cache_set_int(m: &mut HashMap<String, Value>, key: &str, value: i64) {
994    m.insert(key.to_string(), Value::Int(value));
995}
996
997fn cache_bool_field(m: &HashMap<String, Value>, key: &str) -> bool {
998    matches!(m.get(key), Some(Value::Bool(true)))
999}
1000
1001fn cache_set_bool(m: &mut HashMap<String, Value>, key: &str, value: bool) {
1002    m.insert(key.to_string(), Value::Bool(value));
1003}
1004
1005// Reset the per-kind bookkeeping that a `clear()` must drop, mirroring the TS
1006// `ArrayCache` / `ArrayCacheByTimestamp` `clear()` overrides (base/ws/Cache.ts):
1007// the keyed caches find rows through the hashmap and report new-update counts,
1008// so a `clear()` that only truncates `_data` leaves the hashmap + counters
1009// claiming rows that are gone — `getLimit()` then keeps reporting phantom
1010// updates and the next `append` merges into an orphaned reference. Only fields
1011// already present are reset (guards the bare-marker fallback path). The caller
1012// truncates `_data` separately.
1013fn cache_reset_bookkeeping(state: &mut HashMap<String, Value>) {
1014    for k in ["hashmap", "_newUpdatesBySymbol", "_seenUpdatesBySymbol", "_seenUpdatesAll",
1015              "_clearUpdatesBySymbol", "_sizeTracker"] {
1016        if state.contains_key(k) {
1017            state.insert(k.to_string(), Value::Map(HashMap::new()));
1018        }
1019    }
1020    if state.contains_key("_allNewUpdates") { cache_set_int(state, "_allNewUpdates", 0); }
1021    if state.contains_key("_newUpdates") { cache_set_int(state, "_newUpdates", 0); }
1022    if state.contains_key("_clearAllUpdates") { cache_set_bool(state, "_clearAllUpdates", false); }
1023    if state.contains_key("_clearUpdates") { cache_set_bool(state, "_clearUpdates", false); }
1024}
1025
1026// ── ArrayCache update-counter scopes ────────────────────────────────────────
1027// The keyed caches (BySymbolById / ByOutcomeById / BySymbolBySide) count the
1028// distinct second-level keys (id / side) seen since the last poll, kept in TWO
1029// independent scopes so a symbol-scoped poll and a global poll clear each other
1030// without interfering (mirrors `seenUpdatesBySymbol` / `seenUpdatesAll` in
1031// base/ws/Cache.ts). A "set" is a `Map<key2, Bool>` nested under `field[key1]`.
1032
1033// Apply a pending global-scope clear at the top of `append` (TS `clearAllUpdates`).
1034fn cache_apply_clear_all(m: &mut HashMap<String, Value>) {
1035    if cache_bool_field(m, "_clearAllUpdates") {
1036        cache_set_bool(m, "_clearAllUpdates", false);
1037        cache_set_int(m, "_allNewUpdates", 0);
1038        cache_dict_field_mut(m, "_seenUpdatesAll").clear();
1039    }
1040}
1041
1042// Take (and reset) the pending symbol-scoped clear flag for `key1`.
1043fn cache_take_symbol_clear(m: &mut HashMap<String, Value>, key1: &str) -> bool {
1044    let cs = cache_dict_field_mut(m, "_clearUpdatesBySymbol");
1045    if matches!(cs.get(key1), Some(Value::Bool(true))) {
1046        cs.insert(key1.to_string(), Value::Bool(false));
1047        true
1048    } else {
1049        false
1050    }
1051}
1052
1053// Add `key2` to the seen-set `field[key1]`; returns the resulting set size.
1054fn cache_seen_add(m: &mut HashMap<String, Value>, field: &str, key1: &str, key2: &str) -> i64 {
1055    let outer = cache_dict_field_mut(m, field);
1056    let set = outer.entry(key1.to_string()).or_insert_with(|| Value::Map(HashMap::new()));
1057    if let Value::Dict(sd) = set {
1058        let sd = Arc::make_mut(sd);
1059        sd.insert(key2.to_string(), Value::Bool(true));
1060        sd.len() as i64
1061    } else {
1062        0
1063    }
1064}
1065
1066// Size of the seen-set `field[key1]` (0 if absent).
1067fn cache_seen_size(m: &mut HashMap<String, Value>, field: &str, key1: &str) -> i64 {
1068    match cache_dict_field_mut(m, field).get(key1) {
1069        Some(Value::Dict(sd)) => sd.len() as i64,
1070        _ => 0,
1071    }
1072}
1073
1074// Empty the seen-set `field[key1]` (leaves the bucket in place).
1075fn cache_seen_clear(m: &mut HashMap<String, Value>, field: &str, key1: &str) {
1076    if let Some(Value::Dict(sd)) = cache_dict_field_mut(m, field).get_mut(key1) {
1077        Arc::make_mut(sd).clear();
1078    }
1079}
1080
1081// Remove `key2` from the seen-set `field[key1]`; returns whether it was present.
1082// Drops the outer bucket once its set is empty (TS eviction cleanup).
1083fn cache_seen_remove(m: &mut HashMap<String, Value>, field: &str, key1: &str, key2: &str) -> bool {
1084    let outer = cache_dict_field_mut(m, field);
1085    let (removed, empty) = if let Some(Value::Dict(sd)) = outer.get_mut(key1) {
1086        let sd = Arc::make_mut(sd);
1087        let removed = sd.shift_remove(key2).is_some();
1088        (removed, sd.is_empty())
1089    } else {
1090        (false, false)
1091    };
1092    if empty { outer.shift_remove(key1); }
1093    removed
1094}
1095
1096// ── Shared cache backing store ──────────────────────────────────────────────
1097// ArrayCache & friends must survive COW clones the way order-book sides do: a
1098// handler creates a cache, stores a *clone* in `self.ohlcvs[sym][tf]`, appends
1099// to the local, then re-reads the stored clone to resolve (gate watchOHLCV).
1100// With the rolling buffer + hashmap + counters kept in the Dict, the clone and
1101// the local diverge on the first append (Arc::make_mut) and the re-read is
1102// empty. So hold the whole mutable cache state (`_data`, `hashmap`, counters)
1103// in a registry keyed by a stable `__cache_id`; every COW clone shares it.
1104static CACHE_STORE: once_cell::sync::Lazy<std::sync::Mutex<std::collections::HashMap<i64, HashMap<String, Value>>>> =
1105    once_cell::sync::Lazy::new(|| std::sync::Mutex::new(std::collections::HashMap::new()));
1106static NEXT_CACHE_ID: std::sync::atomic::AtomicI64 = std::sync::atomic::AtomicI64::new(1);
1107
1108/// Register a cache's initial mutable state, returning its shared id.
1109pub(crate) fn alloc_cache_id(initial: HashMap<String, Value>) -> i64 {
1110    let id = NEXT_CACHE_ID.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1111    CACHE_STORE.lock().unwrap().insert(id, initial);
1112    id
1113}
1114
1115fn cache_id_of(v: &Value) -> Option<i64> {
1116    match v {
1117        Value::Dict(d) => match d.get("__cache_id") { Some(Value::Int(n)) => Some(*n), _ => None },
1118        _ => None,
1119    }
1120}
1121fn cache_id_of_m(m: &HashMap<String, Value>) -> Option<i64> {
1122    match m.get("__cache_id") { Some(Value::Int(n)) => Some(*n), _ => None }
1123}
1124
1125fn with_cache_cell<R>(id: i64, f: impl FnOnce(&mut HashMap<String, Value>) -> R) -> R {
1126    let mut g = CACHE_STORE.lock().unwrap();
1127    let cell = g.entry(id).or_insert_with(HashMap::new);
1128    f(cell)
1129}
1130
1131/// Snapshot a cache marker's rolling buffer (from the shared cell if it carries
1132/// a `__cache_id`, else the inline `_data` field for legacy markers).
1133fn cache_data_snapshot(m: &HashMap<String, Value>) -> Vec<Value> {
1134    if let Some(id) = cache_id_of_m(m) {
1135        return with_cache_cell(id, |c| match c.get("_data") {
1136            Some(Value::Arr(a)) => (**a).clone(),
1137            _ => Vec::new(),
1138        });
1139    }
1140    match m.get("_data") { Some(Value::Arr(a)) => (**a).clone(), _ => Vec::new() }
1141}
1142
1143fn cache_len_of(m: &HashMap<String, Value>) -> usize {
1144    if let Some(id) = cache_id_of_m(m) {
1145        return with_cache_cell(id, |c| match c.get("_data") { Some(Value::Arr(a)) => a.len(), _ => 0 });
1146    }
1147    match m.get("_data") { Some(Value::Arr(a)) => a.len(), _ => 0 }
1148}
1149
1150fn cache_at(m: &HashMap<String, Value>, i: usize) -> Value {
1151    if let Some(id) = cache_id_of_m(m) {
1152        return with_cache_cell(id, |c| match c.get("_data") {
1153            Some(Value::Arr(a)) => a.get(i).cloned().unwrap_or(Value::Null),
1154            _ => Value::Null,
1155        });
1156    }
1157    match m.get("_data") { Some(Value::Arr(a)) => a.get(i).cloned().unwrap_or(Value::Null), _ => Value::Null }
1158}
1159
1160/// Public: cache buffer length, or None when `m` isn't a cache marker.
1161pub(crate) fn cache_len_of_marker(m: &HashMap<String, Value>) -> Option<usize> {
1162    if m.contains_key("__cacheKind") { Some(cache_len_of(m)) } else { None }
1163}
1164
1165pub(crate) fn cache_append(target: &mut Value, item: Value) {
1166    let kind = cache_kind(target).unwrap_or_default();
1167    let cap = cache_max_size(target);
1168    if let Some(id) = cache_id_of(target) {
1169        with_cache_cell(id, |m| cache_append_inner(m, &kind, cap, item));
1170    } else if let Value::Dict(m_arc) = target {
1171        let m = Arc::make_mut(m_arc);
1172        cache_append_inner(m, &kind, cap, item);
1173    }
1174}
1175
1176fn cache_append_inner(m: &mut HashMap<String, Value>, kind: &str, cap: Option<usize>, item: Value) {
1177    {
1178        match kind {
1179            "ArrayCache" => {
1180                let data = cache_data_mut(m);
1181                if let Some(cap) = cap { if data.len() == cap { data.remove(0); } }
1182                data.push(item.clone());
1183                // Base ArrayCache counts every append (not distinct ids), per scope.
1184                cache_apply_clear_all(m);
1185                let sym = cache_str_field(&item, "symbol").unwrap_or_default();
1186                if cache_take_symbol_clear(m, &sym) {
1187                    cache_dict_field_mut(m, "_newUpdatesBySymbol").insert(sym.clone(), Value::Int(0));
1188                }
1189                {
1190                    let nubs = cache_dict_field_mut(m, "_newUpdatesBySymbol");
1191                    let cur = match nubs.get(&sym) { Some(Value::Int(n)) => *n, _ => 0 };
1192                    nubs.insert(sym, Value::Int(cur + 1));
1193                }
1194                let all = cache_int_field(m, "_allNewUpdates");
1195                cache_set_int(m, "_allNewUpdates", all + 1);
1196            }
1197            "ArrayCacheByTimestamp" => {
1198                let ts_key = match item {
1199                    Value::Arr(ref a) => match a.first() {
1200                        Some(Value::Int(n))   => n.to_string(),
1201                        Some(Value::Float(f)) => f.to_string(),
1202                        Some(Value::Str(s))   => s.to_string(),
1203                        _ => String::new(),
1204                    },
1205                    _ => String::new(),
1206                };
1207                let existing_idx = {
1208                    let hm = cache_dict_field_mut(m, "hashmap");
1209                    match hm.get(&ts_key) { Some(Value::Int(n)) => Some(*n as usize), _ => None }
1210                };
1211                if let Some(idx) = existing_idx {
1212                    let data = cache_data_mut(m);
1213                    if idx < data.len() && data[idx] != item { data[idx] = item.clone(); }
1214                } else {
1215                    // Evict if at cap; shift hashmap indices down.
1216                    let evicting = match cap { Some(c) => {
1217                        let data_len = cache_data_mut(m).len();
1218                        data_len == c
1219                    }, None => false };
1220                    if evicting {
1221                        let removed = {
1222                            let data = cache_data_mut(m);
1223                            if data.is_empty() { Value::Null } else { data.remove(0) }
1224                        };
1225                        let removed_key = match &removed {
1226                            Value::Arr(a) => match a.first() {
1227                                Some(Value::Int(n))   => n.to_string(),
1228                                Some(Value::Float(f)) => f.to_string(),
1229                                Some(Value::Str(s))   => s.to_string(),
1230                                _ => String::new(),
1231                            },
1232                            _ => String::new(),
1233                        };
1234                        let hm = cache_dict_field_mut(m, "hashmap");
1235                        hm.shift_remove(&removed_key);
1236                        for v in hm.values_mut() {
1237                            if let Value::Int(n) = v { *n = n.saturating_sub(1); }
1238                        }
1239                    }
1240                    let new_idx = {
1241                        let data = cache_data_mut(m);
1242                        let i = data.len();
1243                        data.push(item);
1244                        i
1245                    };
1246                    let hm = cache_dict_field_mut(m, "hashmap");
1247                    hm.insert(ts_key.clone(), Value::Int(new_idx as i64));
1248                }
1249                // size tracker / new updates
1250                if cache_bool_field(m, "_clearUpdates") {
1251                    cache_set_bool(m, "_clearUpdates", false);
1252                    let st = cache_dict_field_mut(m, "_sizeTracker");
1253                    st.clear();
1254                }
1255                {
1256                    let st = cache_dict_field_mut(m, "_sizeTracker");
1257                    st.insert(ts_key, Value::Bool(true));
1258                }
1259                let st_len = match m.get("_sizeTracker") {
1260                    Some(Value::Dict(d)) => d.len() as i64,
1261                    _ => 0,
1262                };
1263                cache_set_int(m, "_newUpdates", st_len);
1264            }
1265            "ArrayCacheBySymbolById" | "ArrayCacheBySymbolBySide" | "ArrayCacheByOutcomeById" => {
1266                // ArrayCacheByOutcomeById keys the outer bucket on `outcome` — prediction
1267                // markets stream several outcomes of one market that can share an order id,
1268                // so a symbol-keyed lookup would merge two distinct outcomes into one row.
1269                // The others key on `symbol`. Second level is `id` except BySymbolBySide.
1270                let key1_name = if kind == "ArrayCacheByOutcomeById" { "outcome" } else { "symbol" };
1271                let symbol = cache_str_field(&item, key1_name).unwrap_or_default();
1272                let key2_name = if kind == "ArrayCacheBySymbolBySide" { "side" } else { "id" };
1273                let key2 = cache_str_field(&item, key2_name).unwrap_or_default();
1274                let was_duplicate = {
1275                    let hm = cache_dict_field_mut(m, "hashmap");
1276                    let bucket = hm.entry(symbol.clone())
1277                        .or_insert_with(|| Value::Map(HashMap::new()));
1278                    if let Value::Dict(bd) = bucket {
1279                        Arc::make_mut(bd);
1280                    }
1281                    if let Some(Value::Dict(bd)) = hm.get(&symbol) {
1282                        bd.contains_key(&key2)
1283                    } else { false }
1284                };
1285                let item_to_store = if was_duplicate {
1286                    let merged = {
1287                        let hm = cache_dict_field_mut(m, "hashmap");
1288                        let bucket = hm.get(&symbol).cloned();
1289                        let existing = match bucket {
1290                            Some(Value::Dict(bd)) => bd.get(&key2).cloned(),
1291                            _ => None,
1292                        };
1293                        match (existing, item.clone()) {
1294                            (Some(Value::Dict(old)), Value::Dict(new_)) => {
1295                                let mut merged = (*old).clone();
1296                                for (k, v) in new_.iter() { merged.insert(k.clone(), v.clone()); }
1297                                Value::Dict(Arc::new(merged))
1298                            }
1299                            (_, new_) => new_,
1300                        }
1301                    };
1302                    {
1303                        let hm = cache_dict_field_mut(m, "hashmap");
1304                        let bucket = hm.entry(symbol.clone())
1305                            .or_insert_with(|| Value::Map(HashMap::new()));
1306                        if let Value::Dict(bd) = bucket {
1307                            Arc::make_mut(bd).insert(key2.clone(), merged.clone());
1308                        }
1309                    }
1310                    // Remove the existing slot from _data.
1311                    {
1312                        let data = cache_data_mut(m);
1313                        if let Some(pos) = data.iter().position(|x| {
1314                            cache_str_field(x, key2_name).as_deref() == Some(&key2)
1315                                && cache_str_field(x, key1_name).as_deref() == Some(&symbol)
1316                        }) { data.remove(pos); }
1317                    }
1318                    merged
1319                } else {
1320                    let hm = cache_dict_field_mut(m, "hashmap");
1321                    let bucket = hm.entry(symbol.clone())
1322                        .or_insert_with(|| Value::Map(HashMap::new()));
1323                    if let Value::Dict(bd) = bucket {
1324                        Arc::make_mut(bd).insert(key2.clone(), item.clone());
1325                    }
1326                    item.clone()
1327                };
1328                // Evict from front if at cap.
1329                let evicting = match cap { Some(c) => {
1330                    cache_data_mut(m).len() == c
1331                }, None => false };
1332                if evicting {
1333                    let removed = {
1334                        let data = cache_data_mut(m);
1335                        if data.is_empty() { Value::Null } else { data.remove(0) }
1336                    };
1337                    let r_sym = cache_str_field(&removed, key1_name).unwrap_or_default();
1338                    let r_key2 = cache_str_field(&removed, key2_name).unwrap_or_default();
1339                    {
1340                        let hm = cache_dict_field_mut(m, "hashmap");
1341                        let now_empty = if let Some(Value::Dict(bd)) = hm.get_mut(&r_sym) {
1342                            let bd = Arc::make_mut(bd);
1343                            bd.shift_remove(&r_key2);
1344                            bd.is_empty()
1345                        } else { false };
1346                        // Drop the emptied outer bucket, else a stream of short-lived
1347                        // keys leaks one empty object per key forever (mirrors TS
1348                        // `delete this.hashmap[deleteKey]` when its last id is gone).
1349                        if now_empty { hm.shift_remove(&r_sym); }
1350                    }
1351                    // The evicted key2 leaves both update scopes; a single-scope
1352                    // poller never fires the other scope's clear, so decrement the
1353                    // counts here or they would report the evicted id forever.
1354                    if cache_seen_remove(m, "_seenUpdatesBySymbol", &r_sym, &r_key2) {
1355                        let nubs = cache_dict_field_mut(m, "_newUpdatesBySymbol");
1356                        if let Some(Value::Int(n)) = nubs.get(&r_sym).cloned() {
1357                            nubs.insert(r_sym.clone(), Value::Int(n - 1));
1358                        }
1359                    }
1360                    if cache_seen_remove(m, "_seenUpdatesAll", &r_sym, &r_key2) {
1361                        let all = cache_int_field(m, "_allNewUpdates");
1362                        cache_set_int(m, "_allNewUpdates", all - 1);
1363                    }
1364                }
1365                cache_data_mut(m).push(item_to_store);
1366
1367                // Keyed caches count the distinct second-level keys (id / side)
1368                // seen per scope. Mirror ArrayCacheBySymbolById/BySymbolBySide
1369                // .append (base/ws/Cache.ts): symbol scope and global scope keep
1370                // independent seen-sets, each cleared only by its own poll.
1371                cache_apply_clear_all(m);
1372                if cache_take_symbol_clear(m, &symbol) {
1373                    cache_seen_clear(m, "_seenUpdatesBySymbol", &symbol);
1374                }
1375                let sz = cache_seen_add(m, "_seenUpdatesBySymbol", &symbol, &key2);
1376                cache_dict_field_mut(m, "_newUpdatesBySymbol").insert(symbol.clone(), Value::Int(sz));
1377                let before = cache_seen_size(m, "_seenUpdatesAll", &symbol);
1378                let after = cache_seen_add(m, "_seenUpdatesAll", &symbol, &key2);
1379                let all = cache_int_field(m, "_allNewUpdates");
1380                cache_set_int(m, "_allNewUpdates", all + (after - before));
1381            }
1382            _ => {}
1383        }
1384    }
1385}
1386
1387
1388pub(crate) fn cache_get_limit(target: &mut Value, symbol: Value, limit: Value) -> Value {
1389    let kind = cache_kind(target).unwrap_or_default();
1390    if let Some(id) = cache_id_of(target) {
1391        return with_cache_cell(id, |m| cache_get_limit_inner(m, &kind, symbol, limit));
1392    }
1393    if let Value::Dict(m_arc) = target {
1394        let m = Arc::make_mut(m_arc);
1395        cache_get_limit_inner(m, &kind, symbol, limit)
1396    } else {
1397        limit
1398    }
1399}
1400
1401// Mirrors `ArrayCache.getLimit` (base/ws/Cache.ts). A `symbol` arg polls the
1402// symbol scope and arms its clear; `undefined` (Null) polls the global scope.
1403// The count is `undefined` only when the key was never seen — then the caller's
1404// `limit` passes through unclamped.
1405fn cache_get_limit_inner(m: &mut HashMap<String, Value>, kind: &str, symbol: Value, limit: Value) -> Value {
1406    {
1407        // `ArrayCacheByTimestamp` doesn't track per-symbol updates —
1408        // both `getLimit(undefined, …)` and `getLimit(sym, …)` return
1409        // `this.newUpdates` and arm a single global `clearUpdates` flag.
1410        if kind == "ArrayCacheByTimestamp" {
1411            let v = cache_int_field(m, "_newUpdates");
1412            cache_set_bool(m, "_clearUpdates", true);
1413            return match limit {
1414                Value::Int(l) => Value::Int(v.min(l)),
1415                _             => Value::Int(v),
1416            };
1417        }
1418        let new_updates_value: Option<i64> = match &symbol {
1419            Value::Null => {
1420                cache_set_bool(m, "_clearAllUpdates", true);
1421                Some(cache_int_field(m, "_allNewUpdates"))
1422            }
1423            Value::Str(sym) => {
1424                let v = match cache_dict_field_mut(m, "_newUpdatesBySymbol").get(sym.as_ref()) {
1425                    Some(Value::Int(n)) => Some(*n),
1426                    _ => None,
1427                };
1428                cache_dict_field_mut(m, "_clearUpdatesBySymbol")
1429                    .insert(sym.to_string(), Value::Bool(true));
1430                v
1431            }
1432            _ => None,
1433        };
1434        match (new_updates_value, &limit) {
1435            (None,    _)              => limit.clone(),
1436            (Some(v), Value::Int(l))  => Value::Int(v.min(*l)),
1437            (Some(v), _)              => Value::Int(v),
1438        }
1439    }
1440}
1441
1442// ────────────────────────────────────────────────────────────────────────────
1443// WS order-book helpers — operate on the `Value::Dict` markers from
1444// `crate::pro::order_book`. Tag layout:
1445//   * `__bookKind`  ∈ {OrderBook, IndexedOrderBook, CountedOrderBook}
1446//   * `__sideKind`  ∈ {OrderBookSide, IndexedOrderBookSide,
1447//                      CountedOrderBookSide}  (carried under `bids`/`asks`)
1448// ────────────────────────────────────────────────────────────────────────────
1449
1450fn as_f64(v: &Value) -> f64 {
1451    match v {
1452        Value::Float(f) => *f,
1453        Value::Int(n)   => *n as f64,
1454        Value::Str(s)   => s.parse().unwrap_or(0.0),
1455        _ => 0.0,
1456    }
1457}
1458
1459fn book_kind(v: &Value) -> Option<String> {
1460    match v { Value::Dict(d) => match d.get("__bookKind") {
1461        Some(Value::Str(s)) => Some(s.to_string()), _ => None,
1462    }, _ => None }
1463}
1464
1465// ────────────────────────────────────────────────────────────────────────────
1466// Shared book scalar-metadata store.
1467//
1468// Like side entries, an OrderBook's scalar fields must be shared across clones:
1469// WS handlers mutate a book pulled out of `self.orderbooks` (a COW clone) and
1470// expect the write visible on the next message — okx's per-message seqId nonce
1471// check reads the book's `nonce`, written inside `handle_order_book_message` on
1472// a clone. These fields live in a store keyed by a stable `__book_id`; bids/asks
1473// stay in the Dict (their entries are already shared via `__side_id`).
1474static BOOK_META: once_cell::sync::Lazy<std::sync::Mutex<std::collections::HashMap<i64, HashMap<String, Value>>>> =
1475    once_cell::sync::Lazy::new(|| std::sync::Mutex::new(std::collections::HashMap::new()));
1476static NEXT_BOOK_ID: std::sync::atomic::AtomicI64 = std::sync::atomic::AtomicI64::new(1);
1477
1478/// Scalar book fields that live in the shared meta store (not the Dict).
1479fn is_book_meta_key(k: &str) -> bool {
1480    matches!(k, "timestamp" | "datetime" | "nonce" | "symbol" | "checksum")
1481}
1482
1483pub(crate) fn alloc_book_id() -> i64 {
1484    let id = NEXT_BOOK_ID.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1485    BOOK_META.lock().unwrap().insert(id, HashMap::new());
1486    id
1487}
1488
1489fn book_id_of(m: &HashMap<String, Value>) -> Option<i64> {
1490    match m.get("__book_id") { Some(Value::Int(n)) => Some(*n), _ => None }
1491}
1492
1493fn book_meta_get(id: i64, k: &str) -> Value {
1494    BOOK_META.lock().unwrap().get(&id).and_then(|m| m.get(k).cloned()).unwrap_or(Value::Null)
1495}
1496
1497pub(crate) fn book_meta_set(id: i64, k: &str, v: Value) {
1498    let mut g = BOOK_META.lock().unwrap();
1499    g.entry(id).or_default().insert(k.to_string(), v);
1500}
1501
1502fn book_meta_snapshot(id: i64) -> Vec<(String, Value)> {
1503    BOOK_META.lock().unwrap().get(&id)
1504        .map(|m| m.iter().map(|(k, v)| (k.clone(), v.clone())).collect())
1505        .unwrap_or_default()
1506}
1507
1508// A JS `OrderBook` also carries a mutable `cache` array — venues that fetch a
1509// REST/`req` snapshot buffer live deltas into `orderbook.cache` while the
1510// snapshot is in flight (binance, htx, …). Like the sides/meta, the cache must
1511// be shared across clones: `orderbook.cache.push(msg)` transpiles to
1512// `append_to_array(get_value(&book, "cache"), msg)`, and get_value returns a COW
1513// clone. So `get_value(book, "cache")` returns a lightweight handle carrying
1514// `__book_cache_id`, and length/index/append/clear route through this store.
1515static BOOK_CACHE: once_cell::sync::Lazy<std::sync::Mutex<std::collections::HashMap<i64, Vec<Value>>>> =
1516    once_cell::sync::Lazy::new(|| std::sync::Mutex::new(std::collections::HashMap::new()));
1517
1518/// Build a cache handle for a book id (returned by `get_value(book, "cache")`).
1519fn book_cache_handle(id: i64) -> Value {
1520    let mut h = HashMap::new();
1521    h.insert("__book_cache_id".to_string(), Value::Int(id));
1522    Value::Dict(Arc::new(h))
1523}
1524
1525fn book_cache_id_of(m: &HashMap<String, Value>) -> Option<i64> {
1526    match m.get("__book_cache_id") { Some(Value::Int(n)) => Some(*n), _ => None }
1527}
1528
1529pub(crate) fn book_cache_push(id: i64, v: Value) {
1530    BOOK_CACHE.lock().unwrap().entry(id).or_default().push(v);
1531}
1532
1533fn book_cache_len(id: i64) -> usize {
1534    BOOK_CACHE.lock().unwrap().get(&id).map(|c| c.len()).unwrap_or(0)
1535}
1536
1537/// Length of a cache handle Dict's backing store, or None if `m` isn't a handle.
1538pub(crate) fn book_cache_len_of(m: &HashMap<String, Value>) -> Option<usize> {
1539    book_cache_id_of(m).map(book_cache_len)
1540}
1541
1542/// If `m` is a tagged live-subscriptions snapshot, apply `client.subscriptions
1543/// [key] = val` to the live WS client and return true.
1544pub(crate) fn try_ws_subs_write(m: &HashMap<String, Value>, key: &str, val: &Value) -> bool {
1545    if key == "__ws_subs_url" { return false; }
1546    if let Some(Value::Str(url)) = m.get("__ws_subs_url") {
1547        crate::pro::ws_client::value_subs_insert(url, key, val.clone());
1548        return true;
1549    }
1550    false
1551}
1552
1553/// If `m` is a tagged subscription dict (`__ws_sub_ref`), persist a field write
1554/// `subscription[key] = val` to the live WS client and return true.
1555pub(crate) fn try_ws_sub_field_write(m: &HashMap<String, Value>, key: &str, val: &Value) -> bool {
1556    if key == "__ws_sub_ref" { return false; }
1557    if let Some(Value::Str(subref)) = m.get("__ws_sub_ref") {
1558        crate::pro::ws_client::value_sub_field_write(subref, key, val.clone());
1559        return true;
1560    }
1561    false
1562}
1563
1564/// If `m` is a tagged live-subscriptions snapshot, apply `delete
1565/// client.subscriptions[key]` to the live WS client and return true.
1566pub(crate) fn try_ws_subs_remove(m: &HashMap<String, Value>, key: &str) -> bool {
1567    if let Some(Value::Str(url)) = m.get("__ws_subs_url") {
1568        crate::pro::ws_client::value_subs_remove(url, key);
1569        return true;
1570    }
1571    false
1572}
1573
1574/// If `obj` is a cache handle, push `v` into its store and return true.
1575pub(crate) fn try_book_cache_push(obj: &Value, v: &Value) -> bool {
1576    if let Value::Dict(m) = obj {
1577        if let Some(id) = book_cache_id_of(m) { book_cache_push(id, v.clone()); return true; }
1578    }
1579    false
1580}
1581
1582fn book_cache_at(id: i64, i: usize) -> Value {
1583    BOOK_CACHE.lock().unwrap().get(&id).and_then(|c| c.get(i).cloned()).unwrap_or(Value::Null)
1584}
1585
1586/// Replace a book's cache contents (from `book.cache = [...]`, usually to clear).
1587pub(crate) fn book_cache_set(id: i64, items: Vec<Value>) {
1588    BOOK_CACHE.lock().unwrap().insert(id, items);
1589}
1590
1591/// Snapshot a WS cache's rolling buffer as a plain array. Handles both the
1592/// `_data`-backed ArrayCache / ArrayCacheByTimestamp (trades, ohlcv, tickers)
1593/// and the registry-backed order-book cache handle. Returns `None` when `v`
1594/// isn't a cache — `to_array` then falls back to its generic Dict handling.
1595/// Without this, `to_array(cache)` would surface the cache's meta fields
1596/// (`__cacheKind`, counters, boolean flags) as if they were entries.
1597pub fn cache_entries_as_value(v: &Value) -> Option<Value> {
1598    if let Value::Dict(m) = v {
1599        if let Some(id) = book_cache_id_of(m) {
1600            let items = BOOK_CACHE.lock().unwrap().get(&id).cloned().unwrap_or_default();
1601            return Some(Value::Array(items));
1602        }
1603        if m.contains_key("__cacheKind") {
1604            return Some(Value::Array(cache_data_snapshot(m)));
1605        }
1606    }
1607    None
1608}
1609
1610/// If `m` is a shared book and `k` a meta key, write `v` to the book store and
1611/// return true (the caller should skip its own Dict insert); else false.
1612pub(crate) fn try_book_meta_write(m: &HashMap<String, Value>, k: &str, v: &Value) -> bool {
1613    if is_book_meta_key(k) {
1614        if let Some(id) = book_id_of(m) { book_meta_set(id, k, v.clone()); return true; }
1615    }
1616    // `book.cache = [...]` — replace the shared cache store (usually a clear).
1617    if k == "cache" {
1618        if let Some(id) = book_id_of(m) {
1619            let items = match v { Value::Arr(a) => a.as_ref().clone(), _ => Vec::new() };
1620            book_cache_set(id, items);
1621            return true;
1622        }
1623    }
1624    false
1625}
1626
1627/// Expand a shared book Dict into a plain Dict carrying its meta fields (for
1628/// serialization / equality). Strips `__book_id` so the result is inert.
1629pub fn book_fields_as_value(v: &Value) -> Option<Value> {
1630    match v {
1631        Value::Dict(d) if d.contains_key("__book_id") => {
1632            let mut out: HashMap<String, Value> = (**d).clone();
1633            out.shift_remove("__book_id");
1634            if let Some(Value::Int(id)) = d.get("__book_id") {
1635                if let Some(meta) = BOOK_META.lock().unwrap().get(id) {
1636                    for (k, val) in meta.iter() { out.insert(k.clone(), val.clone()); }
1637                }
1638            }
1639            Some(Value::Dict(Arc::new(out)))
1640        }
1641        _ => None,
1642    }
1643}
1644
1645// ────────────────────────────────────────────────────────────────────────────
1646// Shared side backing store.
1647//
1648// In JS an `OrderBookSide` is a mutable object; the WS handlers routinely do
1649// `const bookside = book['asks']; storeDeltas(bookside, deltas)` where the
1650// helper mutates `bookside` in place and the change is visible through `book`.
1651// Our `Value` is copy-on-write (Arc), so cloning the side Dict and mutating the
1652// clone (the transpiled `handle_deltas(side.clone(), …)` shape) would lose the
1653// writes. To restore shared mutability we keep the side's `_entries` (and the
1654// indexed-side `hashmap`) OUTSIDE the Dict, in a global store keyed by a stable
1655// `__side_id` that survives cloning. All reads and writes go through the store,
1656// so every clone of a side Dict points at the same buffer — matching JS.
1657/// One order-book level. The price sort-key is stored inline so the bisect
1658/// reads it straight from the contiguous `entries` Vec instead of chasing a
1659/// per-level `Arc<Vec<Value>>` (the scattered-allocation cache cost L1nkus
1660/// flagged). `entry` keeps the full original level Value (extra columns, string
1661/// forms) so reads, checksums and serialization stay byte-identical.
1662struct Level {
1663    price: f64,   // raw price; the sort key (bids sort on -price)
1664    entry: Value, // the full [price, amount, …] level as delivered
1665}
1666struct SideCell {
1667    entries: Vec<Level>,
1668    hashmap: HashMap<String, Value>,
1669}
1670
1671static SIDE_STORE: once_cell::sync::Lazy<std::sync::Mutex<std::collections::HashMap<i64, SideCell>>> =
1672    once_cell::sync::Lazy::new(|| std::sync::Mutex::new(std::collections::HashMap::new()));
1673static NEXT_SIDE_ID: std::sync::atomic::AtomicI64 = std::sync::atomic::AtomicI64::new(1);
1674
1675/// Allocate a fresh, empty side cell and return its id.
1676fn alloc_side_id() -> i64 {
1677    let id = NEXT_SIDE_ID.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1678    SIDE_STORE.lock().unwrap().insert(id, SideCell { entries: Vec::new(), hashmap: HashMap::new() });
1679    id
1680}
1681
1682/// Clear (but keep) an existing side cell — used on reset so the id stays
1683/// stable across reseeds instead of leaking a new cell each time.
1684fn clear_side_cell(id: i64) {
1685    let mut g = SIDE_STORE.lock().unwrap();
1686    let cell = g.entry(id).or_insert_with(|| SideCell { entries: Vec::new(), hashmap: HashMap::new() });
1687    cell.entries.clear();
1688    cell.hashmap.clear();
1689}
1690
1691fn side_id_of(m: &HashMap<String, Value>) -> Option<i64> {
1692    match m.get("__side_id") { Some(Value::Int(n)) => Some(*n), _ => None }
1693}
1694
1695/// Snapshot a side's entries (clone) — for read paths (indexing, length, JSON).
1696fn side_entries_view(m: &HashMap<String, Value>) -> Vec<Value> {
1697    match side_id_of(m) {
1698        Some(id) => SIDE_STORE.lock().unwrap().get(&id)
1699            .map(|c| c.entries.iter().map(|l| l.entry.clone()).collect()).unwrap_or_default(),
1700        // Legacy fallback: a side Dict that still carries an inline `_entries`.
1701        None => match m.get("_entries") { Some(Value::Arr(a)) => a.as_ref().clone(), _ => Vec::new() },
1702    }
1703}
1704
1705fn side_entry_at(m: &HashMap<String, Value>, i: usize) -> Value {
1706    match side_id_of(m) {
1707        Some(id) => SIDE_STORE.lock().unwrap().get(&id)
1708            .and_then(|c| c.entries.get(i).map(|l| l.entry.clone())).unwrap_or(Value::Null),
1709        None => match m.get("_entries") {
1710            Some(Value::Arr(a)) => a.get(i).cloned().unwrap_or(Value::Null), _ => Value::Null },
1711    }
1712}
1713
1714pub(crate) fn side_entries_len(m: &HashMap<String, Value>) -> usize {
1715    match side_id_of(m) {
1716        Some(id) => SIDE_STORE.lock().unwrap().get(&id).map(|c| c.entries.len()).unwrap_or(0),
1717        None => match m.get("_entries") { Some(Value::Arr(a)) => a.len(), _ => 0 },
1718    }
1719}
1720
1721/// Mutate a side's cell (entries + hashmap) under the store lock. No-op if the
1722/// side carries no `__side_id`.
1723fn with_side_cell<R>(m: &HashMap<String, Value>, f: impl FnOnce(&mut SideCell) -> R) -> Option<R> {
1724    let id = side_id_of(m)?;
1725    let mut g = SIDE_STORE.lock().unwrap();
1726    let cell = g.entry(id).or_insert_with(|| SideCell { entries: Vec::new(), hashmap: HashMap::new() });
1727    Some(f(cell))
1728}
1729
1730/// Public: snapshot a side marker's entries as a `Value` array, or `None` when
1731/// `v` is not a side marker. Entries live in the shared side store (not the
1732/// Dict), so callers that need the raw `[[price, size, …], …]` list — test
1733/// helpers, serializers — go through this.
1734pub fn side_entries_as_value(v: &Value) -> Option<Value> {
1735    match v {
1736        Value::Dict(d) if d.contains_key("__sideKind") => Some(Value::List(side_entries_view(d))),
1737        _ => None,
1738    }
1739}
1740
1741/// `[price, amount]` for one level row (`Value::Arr`), coercing Str/Int/Float.
1742/// Returns `None` for a short/non-numeric row so it can be dropped.
1743fn row_price_amount(row: &Value) -> Option<[f64; 2]> {
1744    let r = match row { Value::Arr(a) => a, _ => return None };
1745    let num = |cell: Option<&Value>| -> f64 {
1746        match cell {
1747            Some(Value::Float(f)) => *f,
1748            Some(Value::Int(n)) => *n as f64,
1749            Some(Value::Str(s)) => s.parse().unwrap_or(f64::NAN),
1750            _ => f64::NAN,
1751        }
1752    };
1753    let p = num(r.first());
1754    let a = num(r.get(1));
1755    if p.is_nan() || a.is_nan() { None } else { Some([p, a]) }
1756}
1757
1758/// Read a side marker's levels as `[price, amount]` pairs straight from the
1759/// shared side store — no intermediate `Value` list is materialised, so the
1760/// typed `OrderBook::from_value` decode reads the book without cloning every
1761/// level. Returns `None` when `v` is not a side marker (the caller then reads a
1762/// plain `Value::Arr`). NaN/short rows are dropped (not valid book levels).
1763pub fn side_price_amounts(v: &Value) -> Option<Vec<[f64; 2]>> {
1764    let d = match v {
1765        Value::Dict(d) if d.contains_key("__sideKind") => d,
1766        _ => return None,
1767    };
1768    let out = match side_id_of(d) {
1769        Some(id) => match SIDE_STORE.lock().unwrap().get(&id) {
1770            Some(cell) => cell.entries.iter().filter_map(|l| row_price_amount(&l.entry)).collect(),
1771            None => Vec::new(),
1772        },
1773        None => match d.get("_entries") {
1774            Some(Value::Arr(a)) => a.iter().filter_map(row_price_amount).collect(),
1775            _ => Vec::new(),
1776        },
1777    };
1778    Some(out)
1779}
1780
1781/// Build a fresh side marker Dict backed by a new (empty) shared cell.
1782pub(crate) fn make_side_marker(side_kind: &str, is_bid: bool, depth: i64) -> Value {
1783    let sid = alloc_side_id();
1784    let mut m = HashMap::new();
1785    m.insert("__sideKind".to_string(), Value::Str(side_kind.to_string().into()));
1786    m.insert("_isBid".to_string(),     Value::Bool(is_bid));
1787    m.insert("_depth".to_string(),     Value::Int(depth));
1788    m.insert("__side_id".to_string(),  Value::Int(sid));
1789    Value::Dict(Arc::new(m))
1790}
1791
1792fn side_kind(v: &Value) -> Option<String> {
1793    match v { Value::Dict(d) => match d.get("__sideKind") {
1794        Some(Value::Str(s)) => Some(s.to_string()), _ => None,
1795    }, _ => None }
1796}
1797
1798fn side_is_bid(m: &HashMap<String, Value>) -> bool {
1799    matches!(m.get("_isBid"), Some(Value::Bool(true)))
1800}
1801
1802fn side_depth(m: &HashMap<String, Value>) -> usize {
1803    match m.get("_depth") {
1804        Some(Value::Int(n)) if *n > 0 => *n as usize,
1805        _ => usize::MAX / 2,
1806    }
1807}
1808
1809fn level_price(entries: &[Level]) -> impl Fn(usize) -> f64 + '_ {
1810    move |i: usize| entries[i].price
1811}
1812
1813fn bisect_left_by(len: usize, target: f64, is_bid: bool, get_price: impl Fn(usize) -> f64) -> usize {
1814    let mut lo = 0usize;
1815    let mut hi = len;
1816    while lo < hi {
1817        let mid = (lo + hi) / 2;
1818        let p = get_price(mid);
1819        let ip = if is_bid { -p } else { p };
1820        if ip < target { lo = mid + 1; } else { hi = mid; }
1821    }
1822    lo
1823}
1824
1825fn delta_field<T>(d: &Value, idx: usize, parse: impl Fn(&Value) -> T, default: T) -> T {
1826    match d {
1827        Value::Arr(a) => match a.get(idx) { Some(v) => parse(v), None => default },
1828        _ => default,
1829    }
1830}
1831
1832fn entry_id(entries: &[Level], i: usize) -> String {
1833    if let Value::Arr(a) = &entries[i].entry {
1834        if let Some(v) = a.get(2) {
1835            return match v {
1836                Value::Str(s) => s.to_string(),
1837                Value::Int(n) => n.to_string(),
1838                _ => String::new(),
1839            };
1840        }
1841    }
1842    String::new()
1843}
1844
1845fn side_store_array(side: &Value, delta: Value) {
1846    let kind = side_kind(side).unwrap_or_default();
1847    let m = match side { Value::Dict(d) => d.as_ref(), _ => return };
1848    let is_bid = side_is_bid(m);
1849    with_side_cell(m, |cell| {
1850    match kind.as_str() {
1851        "OrderBookSide" => {
1852            let price = delta_field(&delta, 0, as_f64, 0.0);
1853            let size  = delta_field(&delta, 1, as_f64, 0.0);
1854            let target = if is_bid { -price } else { price };
1855            let entries = &mut cell.entries;
1856            let idx = bisect_left_by(entries.len(), target, is_bid, level_price(entries));
1857            let matches_here = idx < entries.len()
1858                && (if is_bid { -entries[idx].price } else { entries[idx].price }) == target;
1859            if size != 0.0 {
1860                if matches_here {
1861                    entries[idx] = Level { price, entry: delta };
1862                } else {
1863                    entries.insert(idx, Level { price, entry: delta });
1864                }
1865            } else if matches_here {
1866                entries.remove(idx);
1867            }
1868        }
1869        "CountedOrderBookSide" => {
1870            let price = delta_field(&delta, 0, as_f64, 0.0);
1871            let size  = delta_field(&delta, 1, as_f64, 0.0);
1872            let count = delta_field(&delta, 2, as_f64, 0.0);
1873            // JS gates a counted store on `size && count`, but some venues drive
1874            // a counted book with no numeric count in slot 2 — bitget stores
1875            // `[price, size, [rawPrice, rawSize]]` (the raw pair, for checksums).
1876            // Only treat slot 2 as a count when it's actually a number; otherwise
1877            // gate on size alone so the entry stores.
1878            let has_count = matches!(&delta,
1879                Value::Arr(a) if matches!(a.get(2), Some(Value::Int(_)) | Some(Value::Float(_))));
1880            let store_it = if has_count { size != 0.0 && count != 0.0 } else { size != 0.0 };
1881            let target = if is_bid { -price } else { price };
1882            let entries = &mut cell.entries;
1883            let idx = bisect_left_by(entries.len(), target, is_bid, level_price(entries));
1884            let matches_here = idx < entries.len()
1885                && (if is_bid { -entries[idx].price } else { entries[idx].price }) == target;
1886            if store_it {
1887                if matches_here {
1888                    entries[idx] = Level { price, entry: delta };
1889                } else {
1890                    entries.insert(idx, Level { price, entry: delta });
1891                }
1892            } else if matches_here {
1893                entries.remove(idx);
1894            }
1895        }
1896        "IndexedOrderBookSide" => {
1897            let price_opt = match &delta {
1898                Value::Arr(a) => a.first().and_then(|v| match v {
1899                    Value::Float(f) => Some(*f),
1900                    Value::Int(n)   => Some(*n as f64),
1901                    _ => None,
1902                }),
1903                _ => None,
1904            };
1905            let size = delta_field(&delta, 1, as_f64, 0.0);
1906            let id = match &delta {
1907                Value::Arr(a) => match a.get(2) {
1908                    Some(Value::Str(s)) => s.to_string(),
1909                    Some(Value::Int(n)) => n.to_string(),
1910                    _ => String::new(),
1911                },
1912                _ => String::new(),
1913            };
1914            let mut index_price = price_opt.map(|p| if is_bid { -p } else { p });
1915            let old_price_opt = {
1916                match cell.hashmap.get(&id) {
1917                    Some(Value::Float(f)) => Some(*f),
1918                    Some(Value::Int(n))   => Some(*n as f64),
1919                    _ => None,
1920                }
1921            };
1922            if size != 0.0 {
1923                if let Some(old_price) = old_price_opt {
1924                    index_price = index_price.or(Some(old_price));
1925                    if Some(old_price) == index_price {
1926                        // Find slot by walking from bisect_left
1927                        let target = old_price;
1928                        let raw = if is_bid { -old_price } else { old_price };
1929                        let entries = &mut cell.entries;
1930                        let mut idx = bisect_left_by(entries.len(), target, is_bid, level_price(entries));
1931                        while idx < entries.len() && entry_id(entries, idx) != id { idx += 1; }
1932                        if idx < entries.len() { entries[idx] = Level { price: raw, entry: delta }; }
1933                        return;
1934                    }
1935                    // Different price — remove old slot
1936                    let target = old_price;
1937                    let entries = &mut cell.entries;
1938                    let mut old_idx = bisect_left_by(entries.len(), target, is_bid, level_price(entries));
1939                    while old_idx < entries.len() && entry_id(entries, old_idx) != id { old_idx += 1; }
1940                    if old_idx < entries.len() { entries.remove(old_idx); }
1941                }
1942                let target = match index_price { Some(p) => p, None => return };
1943                let raw = if is_bid { -target } else { target };
1944                // Insert sorted with secondary id tiebreaker
1945                let entries = &mut cell.entries;
1946                let mut idx = bisect_left_by(entries.len(), target, is_bid, level_price(entries));
1947                while idx < entries.len() {
1948                    let ip = if is_bid { -entries[idx].price } else { entries[idx].price };
1949                    if ip != target { break; }
1950                    if entry_id(entries, idx) >= id { break; }
1951                    idx += 1;
1952                }
1953                entries.insert(idx, Level { price: raw, entry: delta });
1954                cell.hashmap.insert(id, Value::Float(target));
1955            } else if let Some(old_price) = old_price_opt {
1956                // Delete by id
1957                let target = old_price;
1958                let entries = &mut cell.entries;
1959                let mut idx = bisect_left_by(entries.len(), target, is_bid, level_price(entries));
1960                while idx < entries.len() && entry_id(entries, idx) != id { idx += 1; }
1961                if idx < entries.len() { entries.remove(idx); }
1962                cell.hashmap.shift_remove(&id);
1963            }
1964        }
1965        _ => {}
1966    }
1967    });
1968}
1969
1970fn side_limit(side: &Value) {
1971    let m = match side { Value::Dict(d) => d.as_ref(), _ => return };
1972    let depth = side_depth(m);
1973    with_side_cell(m, |cell| {
1974        if cell.entries.len() > depth { cell.entries.truncate(depth); }
1975    });
1976}
1977
1978fn book_reseed_sides(book: &mut Value, snapshot: &Value) {
1979    let kind = book_kind(book).unwrap_or_default();
1980    let side_kind_str = match kind.as_str() {
1981        "IndexedOrderBook" => "IndexedOrderBookSide",
1982        "CountedOrderBook" => "CountedOrderBookSide",
1983        _                  => "OrderBookSide",
1984    };
1985    let bids_deltas = crate::get_value(snapshot, &Value::Str("bids".into()));
1986    let asks_deltas = crate::get_value(snapshot, &Value::Str("asks".into()));
1987    if let Value::Dict(book_arc) = book {
1988        let book_m = Arc::make_mut(book_arc);
1989        let depth = match book_m.get("_depth") {
1990            Some(Value::Int(n)) => *n,
1991            _ => i64::MAX / 2,
1992        };
1993        // Rebuild bids/asks. Reuse the existing side's `__side_id` (clearing its
1994        // backing cell) so repeated resets don't leak a fresh cell each time.
1995        for (side_key, deltas, is_bid) in [
1996            ("bids", &bids_deltas, true),
1997            ("asks", &asks_deltas, false),
1998        ] {
1999            let sid = match book_m.get(side_key) {
2000                Some(Value::Dict(d)) => match d.get("__side_id") {
2001                    Some(Value::Int(n)) => { clear_side_cell(*n); *n }
2002                    _ => alloc_side_id(),
2003                },
2004                _ => alloc_side_id(),
2005            };
2006            let mut m = HashMap::new();
2007            m.insert("__sideKind".to_string(),  Value::Str(side_kind_str.to_string().into()));
2008            m.insert("_isBid".to_string(),      Value::Bool(is_bid));
2009            m.insert("_depth".to_string(),      Value::Int(depth));
2010            m.insert("__side_id".to_string(),   Value::Int(sid));
2011            let side = Value::Map(m);
2012            if let Value::Arr(rows) = deltas {
2013                for row in rows.iter() {
2014                    if let Value::Arr(_) = row { side_store_array(&side, row.clone()); }
2015                }
2016            }
2017            book_m.insert(side_key.to_string(), side);
2018        }
2019    }
2020}
2021
2022pub(crate) fn book_limit(book: &mut Value) {
2023    if book_kind(book).is_none() { return; }
2024    if let Value::Dict(arc) = book {
2025        let m = Arc::make_mut(arc);
2026        if let Some(side) = m.get_mut("bids") { side_limit(side); }
2027        if let Some(side) = m.get_mut("asks") { side_limit(side); }
2028    }
2029}
2030
2031pub(crate) fn book_reset(book: &mut Value, snapshot: Value) {
2032    if book_kind(book).is_none() { return; }
2033    book_reseed_sides(book, &snapshot);
2034    let id = match book { Value::Dict(d) => book_id_of(d), _ => None };
2035    if let Some(id) = id {
2036        let ts = match crate::get_value(&snapshot, &Value::Str("timestamp".into())) {
2037            Value::Int(n)   => Some(n),
2038            Value::Float(f) => Some(f as i64),
2039            _ => None,
2040        };
2041        let dt = ts.and_then(|n| chrono::DateTime::<chrono::Utc>::from_timestamp_millis(n)
2042            .map(|t| t.to_rfc3339_opts(chrono::SecondsFormat::Millis, true)));
2043        book_meta_set(id, "timestamp", ts.map(Value::Int).unwrap_or(Value::Null));
2044        book_meta_set(id, "datetime",  dt.map(|s| Value::Str(s.into())).unwrap_or(Value::Null));
2045        book_meta_set(id, "nonce",     crate::get_value(&snapshot, &Value::Str("nonce".into())));
2046        book_meta_set(id, "symbol",    crate::get_value(&snapshot, &Value::Str("symbol".into())));
2047    }
2048}
2049
2050pub(crate) fn book_update(book: &mut Value, snapshot: Value) {
2051    if book_kind(book).is_none() { return; }
2052    // Skip stale updates.
2053    let new_nonce = match crate::get_value(&snapshot, &Value::Str("nonce".into())) {
2054        Value::Int(n) => Some(n), _ => None,
2055    };
2056    let cur_nonce = match book {
2057        Value::Dict(d) => match book_id_of(d).map(|id| book_meta_get(id, "nonce")) {
2058            Some(Value::Int(n)) => Some(n), _ => None,
2059        },
2060        _ => None,
2061    };
2062    if let (Some(n), Some(cur)) = (new_nonce, cur_nonce) {
2063        if n <= cur { return; }
2064    }
2065    book_reset(book, snapshot);
2066}
2067
2068pub(crate) fn book_store_array_side(book: &mut Value, side_key: &str, delta: Value) {
2069    if let Value::Dict(arc) = book {
2070        let m = Arc::make_mut(arc);
2071        if let Some(side) = m.get_mut(side_key) {
2072            side_store_array(side, delta);
2073        }
2074    }
2075}
2076
2077
2078// ─── Value method API exposed to the transpiled tests ─────────────────────
2079
2080impl Value {
2081    /// `book.limit()` — trim both sides to `_depth`. Returns a clone
2082    /// of `self` so transpiled `return book.limit();` lines still
2083    /// match the `-> Value` signature.
2084    pub fn limit(&mut self) -> Value {
2085        book_limit(self);
2086        self.clone()
2087    }
2088
2089    /// `book.reset(snapshot)` — wipe + reseed bids/asks + metadata.
2090    /// Returns self for the same reason as `limit()`. A bare
2091    /// `book.reset()` is also valid (matches the TS `OrderBook` shape);
2092    /// when called without a snapshot, we just rebind the existing one
2093    /// (effectively a no-op metadata refresh).
2094    pub fn reset(&mut self, snapshot: Value) -> Value {
2095        // `client.reset(error)` — a WS client handle (carries "url") rejects its
2096        // pending futures with the error; everything else is an OrderBook
2097        // snapshot reset.
2098        if matches!(&self, Value::Dict(d) if d.contains_key("url") && d.contains_key("subscriptions")) {
2099            return crate::pro::ws_client::value_reset(self, snapshot);
2100        }
2101        book_reset(self, snapshot);
2102        self.clone()
2103    }
2104    /// Zero-arg `reset()` form used by per-exchange WS code that just
2105    /// wants to clear the rolling buffers.
2106    pub fn reset0(&mut self) -> Value {
2107        book_reset(self, Value::Null);
2108        self.clone()
2109    }
2110
2111    /// `book.update(snapshot)` — same as reset but only when the
2112    /// supplied nonce moves forward.
2113    pub fn update(&mut self, snapshot: Value) -> Value {
2114        book_update(self, snapshot);
2115        self.clone()
2116    }
2117
2118    /// `side.store(price, size)` — convenience that builds a 2-element
2119    /// delta. Routed through the side's `store_array`. Only useful on a
2120    /// side marker (returned by `book['bids']`), not the book itself.
2121    pub fn store(&mut self, price: Value, size: Value) {
2122        if side_kind(self).is_some() {
2123            let delta = Value::List(vec![price, size]);
2124            side_store_array(self, delta);
2125        }
2126    }
2127
2128    /// Book-level side mutators — the transpiler rewrites side-extraction
2129    /// patterns (`let bids = book['bids']; bids.X(...)`) into calls on
2130    /// these methods so the mutation reaches the book's actual side
2131    /// dict rather than a COW-cloned copy of it.
2132    pub fn store_to_bids(&mut self, price: Value, size: Value) {
2133        let delta = Value::List(vec![price, size]);
2134        book_store_array_side(self, "bids", delta);
2135    }
2136    pub fn store_to_asks(&mut self, price: Value, size: Value) {
2137        let delta = Value::List(vec![price, size]);
2138        book_store_array_side(self, "asks", delta);
2139    }
2140    pub fn store_array_to_bids(&mut self, delta: Value) {
2141        book_store_array_side(self, "bids", delta);
2142    }
2143    pub fn store_array_to_asks(&mut self, delta: Value) {
2144        book_store_array_side(self, "asks", delta);
2145    }
2146}
2147
2148#[cfg(test)]
2149mod json_int_precision_tests {
2150    use super::Value;
2151
2152    #[test]
2153    fn preserves_large_u64_ids_losslessly() {
2154        // 12345678901234567890 > i64::MAX but ≤ u64::MAX — must not round.
2155        let v: serde_json::Value = serde_json::from_str(r#"{"id": 12345678901234567890}"#).unwrap();
2156        let parsed = Value::from_json(&v);
2157        let id = crate::runtime::get_value(&parsed, &Value::Str("id".into()));
2158        assert_eq!(id, Value::Str("12345678901234567890".into()));
2159    }
2160
2161    #[test]
2162    fn small_ints_stay_ints_floats_stay_floats() {
2163        let v: serde_json::Value = serde_json::from_str(r#"{"a": 42, "b": -7, "c": 1.5}"#).unwrap();
2164        let p = Value::from_json(&v);
2165        assert_eq!(crate::runtime::get_value(&p, &Value::Str("a".into())), Value::Int(42));
2166        assert_eq!(crate::runtime::get_value(&p, &Value::Str("b".into())), Value::Int(-7));
2167        assert_eq!(crate::runtime::get_value(&p, &Value::Str("c".into())), Value::Float(1.5));
2168    }
2169}