@0xmonaco/react 1.0.47 → 1.0.50

package/dist/hooks/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./useAuth";
 export * from "./useFees";
+export * from "./useInstruments";
 export * from "./useMarket";
 export * from "./useMonaco";
 export * from "./useOHLCV";

package/dist/hooks/index.js

@@ -1,5 +1,6 @@
 export * from "./useAuth";
 export * from "./useFees";
+export * from "./useInstruments";
 export * from "./useMarket";
 export * from "./useMonaco";
 export * from "./useOHLCV";

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

@@ -0,0 +1,2 @@
+export * from "./types";
+export { useInstruments } from "./useInstruments";

package/dist/hooks/useInstruments/index.js

@@ -0,0 +1,2 @@
+export * from "./types";
+export { useInstruments } from "./useInstruments";

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

@@ -0,0 +1,34 @@
+import type { InstrumentEventData } from "@0xmonaco/types";
+/**
+ * Return type for the useInstruments hook
+ */
+export interface UseInstrumentsReturn {
+    /**
+     * Current configuration of every market seen on the channel, ordered by
+     * symbol and then trading pair id. Delisted markets stay in the list carrying
+     * `isActive: false` — filter on `isActive` for the tradable set.
+     */
+    instruments: InstrumentEventData[];
+    /** The same entries keyed by trading pair UUID, for direct lookup */
+    instrumentsByPair: Record<string, InstrumentEventData>;
+    /**
+     * Whether a subscription to the instrument channel is currently registered.
+     * This is not a connection indicator: the client accepts subscriptions while
+     * the socket is down and sends them on the next open, so `true` means
+     * "registered", not "receiving".
+     */
+    subscribed: boolean;
+    /**
+     * A rejected subscription request. The core helper validates its arguments
+     * synchronously — passing an empty `tradingPairId` is the reachable case — so
+     * treat this as a bad-usage signal.
+     *
+     * It is deliberately NOT a transport signal: the client registers handlers
+     * regardless of socket state, and logs malformed-frame failures internally,
+     * so connection loss and unparseable frames never appear here. Drive
+     * connection UI from the client's own status/resync callbacks instead.
+     */
+    error: Error | null;
+    /** Clear the current error state */
+    clearError: () => void;
+}

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

@@ -0,0 +1,27 @@
+import type { UseInstrumentsReturn } from "./types";
+/**
+ * Hook for subscribing to real-time instrument configuration via WebSocket (public)
+ *
+ * On subscribe the channel delivers a snapshot of the current active markets
+ * (one `listing` frame each), then live listing, delisting, halt/unhalt and
+ * config-change frames. Every frame carries a market's FULL current
+ * 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.
+ *
+ * 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.
+ *
+ * @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
+ *   surfaced through `error`.
+ */
+export declare function useInstruments(tradingPairId?: string): UseInstrumentsReturn;

package/dist/hooks/useInstruments/useInstruments.js

@@ -0,0 +1,94 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useMonacoSDK } from "../useMonaco";
+const IDLE = {
+    source: undefined,
+    tradingPairId: undefined,
+    byPair: {},
+    subscribed: false,
+    error: null,
+};
+/** Shared empty map, so an out-of-scope render keeps a stable identity. */
+const NO_INSTRUMENTS = {};
+/**
+ * Hook for subscribing to real-time instrument configuration via WebSocket (public)
+ *
+ * On subscribe the channel delivers a snapshot of the current active markets
+ * (one `listing` frame each), then live listing, delisting, halt/unhalt and
+ * config-change frames. Every frame carries a market's FULL current
+ * 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.
+ *
+ * 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.
+ *
+ * @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
+ *   surfaced through `error`.
+ */
+export function useInstruments(tradingPairId) {
+    const { sdk } = useMonacoSDK();
+    const ws = sdk?.ws;
+    const [subscription, setSubscription] = useState(IDLE);
+    // Entries only count while they belong to the subscription the caller is
+    // asking for right now; the effect below realigns them a tick later.
+    const inScope = subscription.source === ws && subscription.tradingPairId === tradingPairId;
+    const clearError = useCallback(() => {
+        setSubscription((prev) => (prev.error === null ? prev : { ...prev, error: null }));
+    }, []);
+    useEffect(() => {
+        if (!ws) {
+            setSubscription({ ...IDLE, tradingPairId });
+            return;
+        }
+        // Only a frame that belongs to *this* subscription may touch state — a
+        // late arrival from a torn-down one must not resurrect old markets.
+        const belongsToThisSubscription = (prev) => prev.source === ws && prev.tradingPairId === tradingPairId;
+        // Claim the scope before subscribing so the first frame, whenever it lands,
+        // already has somewhere in-scope to go.
+        setSubscription({ source: ws, tradingPairId, byPair: {}, subscribed: false, error: null });
+        // `instruments` throws synchronously on a missing handler or an empty pair
+        // id — surface that through `error` instead of letting it escape the effect.
+        let unsubscribe;
+        try {
+            unsubscribe = ws.instruments((event) => {
+                setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, byPair: { ...prev.byPair, [event.tradingPairId]: event.data } } : prev));
+            }, tradingPairId);
+            setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, subscribed: true } : prev));
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, subscribed: false, error } : prev));
+        }
+        return () => {
+            unsubscribe?.();
+            setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, subscribed: false } : prev));
+        };
+    }, [ws, tradingPairId]);
+    const instrumentsByPair = inScope ? subscription.byPair : NO_INSTRUMENTS;
+    // Sorted with plain codepoint comparison rather than `localeCompare`, so the
+    // order does not shift with the runtime locale, and tie-broken on the pair id
+    // because a spot and a perp market can carry the same symbol.
+    const instruments = useMemo(() => Object.values(instrumentsByPair).sort((left, right) => {
+        if (left.symbol !== right.symbol)
+            return left.symbol < right.symbol ? -1 : 1;
+        if (left.tradingPairId === right.tradingPairId)
+            return 0;
+        return left.tradingPairId < right.tradingPairId ? -1 : 1;
+    }), [instrumentsByPair]);
+    return {
+        instruments,
+        instrumentsByPair,
+        subscribed: inScope && subscription.subscribed,
+        error: inScope ? subscription.error : null,
+        clearError,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/react",
-	"version": "1.0.47",
+	"version": "1.0.50",
 	"type": "module",
 	"homepage": "https://docs.0xmonaco.com/sdk/typescript",
 	"main": "./dist/index.js",
@@ -16,8 +16,8 @@
 		"lint": "biome lint ."
 	},
 	"dependencies": {
-		"@0xmonaco/core": "1.0.47",
-		"@0xmonaco/types": "1.0.47"
+		"@0xmonaco/core": "1.0.50",
+		"@0xmonaco/types": "1.0.50"
 	},
 	"devDependencies": {
 		"@types/react": "^19.1.12",