@0xmonaco/react 1.0.51 → 1.0.54

package/dist/hooks/useInstruments/useInstruments.d.ts

@@ -8,17 +8,19 @@ import type { UseInstrumentsReturn } from "./types";
  * configuration rather than a delta, so state is kept as a terminal-state
  * entry per trading pair: each event replaces that market's entry outright.
  *
- * A delisted market keeps its entry with `isActive: false` rather than
- * disappearing, so a consumer can distinguish "no longer tradable" from "never
- * seen"; read `instruments.filter((instrument) => instrument.isActive)` for the
- * tradable set.
+ * A market DELISTED while the socket was up keeps its entry with
+ * `isActive: false` rather than disappearing, so a consumer can distinguish
+ * "no longer tradable" from "never seen"; read
+ * `instruments.filter((instrument) => instrument.isActive)` for the tradable
+ * set.
  *
- * Caveat on reconnect: the server's post-reconnect snapshot covers the markets
- * active at that moment, and the core helper delivers it as ordinary per-market
- * events. A market delisted while the socket was down is simply absent from
- * that snapshot, so its entry here keeps its pre-outage state until the market
- * next emits. Closing that needs a snapshot-boundary signal the channel's
- * handler contract does not currently carry.
+ * Reconnect is the exception, and the snapshot boundary is what makes it
+ * expressible. Each snapshot is the authoritative active-market set at the
+ * moment it was taken, so it REPLACES the map wholesale rather than merging
+ * into it: a market delisted while the socket was down is absent from the
+ * post-reconnect snapshot and leaves this state with it. Merging would have
+ * stranded that market here forever carrying its pre-outage config, because a
+ * delisted market emits nothing further to correct it.
  *
  * @param tradingPairId - Optional trading pair UUID to filter on; omit to
  *   receive every market. An empty string is rejected by the core helper and is

package/dist/hooks/useInstruments/useInstruments.js

@@ -18,17 +18,19 @@ const NO_INSTRUMENTS = {};
  * configuration rather than a delta, so state is kept as a terminal-state
  * entry per trading pair: each event replaces that market's entry outright.
  *
- * A delisted market keeps its entry with `isActive: false` rather than
- * disappearing, so a consumer can distinguish "no longer tradable" from "never
- * seen"; read `instruments.filter((instrument) => instrument.isActive)` for the
- * tradable set.
+ * A market DELISTED while the socket was up keeps its entry with
+ * `isActive: false` rather than disappearing, so a consumer can distinguish
+ * "no longer tradable" from "never seen"; read
+ * `instruments.filter((instrument) => instrument.isActive)` for the tradable
+ * set.
  *
- * Caveat on reconnect: the server's post-reconnect snapshot covers the markets
- * active at that moment, and the core helper delivers it as ordinary per-market
- * events. A market delisted while the socket was down is simply absent from
- * that snapshot, so its entry here keeps its pre-outage state until the market
- * next emits. Closing that needs a snapshot-boundary signal the channel's
- * handler contract does not currently carry.
+ * Reconnect is the exception, and the snapshot boundary is what makes it
+ * expressible. Each snapshot is the authoritative active-market set at the
+ * moment it was taken, so it REPLACES the map wholesale rather than merging
+ * into it: a market delisted while the socket was down is absent from the
+ * post-reconnect snapshot and leaves this state with it. Merging would have
+ * stranded that market here forever carrying its pre-outage config, because a
+ * delisted market emits nothing further to correct it.
  *
  * @param tradingPairId - Optional trading pair UUID to filter on; omit to
  *   receive every market. An empty string is rejected by the core helper and is
@@ -61,7 +63,10 @@ export function useInstruments(tradingPairId) {
         try {
             unsubscribe = ws.instruments((event) => {
                 setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, byPair: { ...prev.byPair, [event.tradingPairId]: event.data } } : prev));
-            }, tradingPairId);
+            }, tradingPairId, (items) => {
+                const byPair = Object.fromEntries(items.map((item) => [item.tradingPairId, item]));
+                setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, byPair } : prev));
+            });
             setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, subscribed: true } : prev));
         }
         catch (err) {

package/dist/hooks/useUserBalances/useUserBalances.d.ts

@@ -1,9 +1,86 @@
-import type { AccountBalance, UserBalanceEvent } from "@0xmonaco/types";
+import type { AccountBalance, UserBalanceEvent, UserBalanceEventData } from "@0xmonaco/types";
 import type { UseUserBalancesReturn } from "./types";
 /**
  * Update an AccountBalance with data from a WebSocket balance event
  */
 export declare function updateBalanceFromEvent(balance: AccountBalance, event: UserBalanceEvent): AccountBalance;
+/**
+ * Apply a subscribe-time balances snapshot to the current list.
+ *
+ * The snapshot is the user's COMPLETE balance set, which is what makes this a
+ * different operation from applying a live event rather than a loop over one:
+ *
+ * - A held asset the snapshot omits has no balance left, so it is zeroed rather
+ *   than left showing a figure that is no longer true. The row itself stays —
+ *   a portfolio needs to render "0 WSEI", not to lose the line.
+ * - The snapshot's totals are taken VERBATIM. A snapshot row is built from the
+ *   same accounts-service read that produced the REST row, so its `total`
+ *   already is the REST `totalBalance` with margin collateral included —
+ *   unlike a live event, whose `total` can describe the spot balance alone and
+ *   therefore needs {@link updateBalanceFromEvent}'s margin reconciliation.
+ *   Running a snapshot row through that would add the derived margin component
+ *   a second time.
+ * - A row for an asset the list does not hold cannot be completed here: the
+ *   wire payload carries no `assetId`, `decimals` or wrapped-native flag. That
+ *   case is reported by {@link snapshotHasUnknownAsset} rather than from here,
+ *   so the caller can decide to re-read WITHOUT doing it inside a state
+ *   updater — React invokes an updater during render, and may invoke it more
+ *   than once, so a flag assigned inside one is not readable afterwards.
+ *
+ * Pure, so the caller can use it inside a state updater.
+ */
+export declare function applyBalanceSnapshot(current: AccountBalance[], items: UserBalanceEventData[]): {
+    balances: AccountBalance[];
+    hasUnknownAsset: boolean;
+};
+/**
+ * Whether the snapshot names an asset the current list does not hold.
+ *
+ * Split out of {@link applyBalanceSnapshot} so a caller can ask the question
+ * before entering a state updater: the answer decides whether to fire a REST
+ * re-read, and a side effect must not depend on an updater having run.
+ */
+export declare function snapshotHasUnknownAsset(current: AccountBalance[], items: UserBalanceEventData[]): boolean;
+/**
+ * Merge a background REST read into the current list without disturbing it.
+ *
+ * The repair this serves has one job: learn about an asset the list does not
+ * hold yet, because the WebSocket payload carries no `assetId`, `decimals` or
+ * wrapped-native flag and so cannot introduce one on its own.
+ *
+ * It must not do more than that. The subscription stays live while the request
+ * is in flight, so an event or snapshot can land in between — and replacing the
+ * list with the response would roll those newer values back, including the
+ * authoritative snapshot figures that triggered the read in the first place.
+ * Rows already held therefore keep their live values untouched, and only
+ * genuinely new assets are appended.
+ *
+ * The initial load and the public `refresh()` still replace: the first runs
+ * before the subscription opens, so nothing newer can exist to lose, and the
+ * second is a deliberate "give me the server's answer" action.
+ */
+export declare function reconcileBalances(current: AccountBalance[], fetched: AccountBalance[]): AccountBalance[];
+/**
+ * Overlay buffered wire state onto rows a REST read has just supplied metadata
+ * for.
+ *
+ * A frame naming a token the list does not hold yet is dropped by the event
+ * handler — there is no row to apply it to — and the repair read that follows
+ * may have queried the server BEFORE that frame. Appending its result would
+ * then leave the token at a value the stream has already moved past, with no
+ * later frame to correct it because every subsequent frame finds a row and
+ * takes the update path. Buffering the newest wire state for an unheld token
+ * and laying it over the row once metadata arrives is what closes that.
+ *
+ * Only entries newer than the read are applied. One buffered BEFORE the read
+ * started is already reflected in its result, and re-applying it would roll the
+ * row back to that older value.
+ */
+export declare function applyBufferedBalances(rows: AccountBalance[], buffered: Map<string, {
+    data: UserBalanceEventData;
+    seq: number;
+    source: "event" | "snapshot";
+}>, readSeq: number): AccountBalance[];
 /**
  * Hook for subscribing to real-time user balance updates via WebSocket (authenticated)
  *