@imbingox/acex 0.4.0-beta.5 → 0.4.0-beta.6

package/docs/api.md

@@ -345,6 +345,7 @@ interface MarketManager {
   readonly events: MarketEventStreams;
 
   loadMarkets(): Promise<void>;
+  reloadMarkets(venue?: Venue): Promise<MarketCatalogReloadSummary[]>;
   listMarkets(venue?: Venue): MarketDefinition[];
   getMarket(venue: Venue, symbol: string): MarketDefinition | undefined;
   getMarkets(symbol: string): MarketDefinition[];
@@ -368,6 +369,7 @@ interface MarketManager {
 
 ```ts
 await client.market.loadMarkets();
+const reloadSummaries = await client.market.reloadMarkets("binance");
 
 const all = client.market.listMarkets();
 const binanceOnly = client.market.listMarkets("binance");
@@ -378,6 +380,25 @@ const allBtcPerp = client.market.getMarkets("BTC/USDT:USDT");
 
 `getMarkets(symbol)` 严格按完整统一 symbol 匹配。
 
+`loadMarkets()` 会懒加载并缓存当前已注册 venue 的市场目录；已加载过的 venue 不会重复拉取。`reloadMarkets(venue?)` 用于主动刷新市场目录：传入 `venue` 时只刷新该 venue，省略时刷新所有已注册 market adapter。它和 `loadMarkets()` 一样不要求 client 已 `start()`，因此可在 `start()` 前或 `stop()` 后调用。
+
+`reloadMarkets()` 返回每个 venue 的刷新摘要：
+
+```ts
+type MarketCatalogReloadSummary = {
+  venue: Venue;
+  added: string[];
+  removed: string[];
+  total: number;
+  ok: boolean;
+  error?: AcexError;
+};
+```
+
+`added` / `removed` 是本次刷新相对旧目录变化的 symbol 列表，`total` 是刷新后该 venue 的目录数量。catalog 拉取失败时，对应 summary 为 `ok: false`，`error.code = "MARKET_CATALOG_LOAD_FAILED"`，旧目录会保留，方法不会因为该 venue 的 catalog 失败而 reject；未注册 runtime adapter 的合法 venue（例如当前 market adapter 未接入的 `bybit`）仍会抛 `VENUE_NOT_SUPPORTED`。
+
+如果刷新会新增 symbol，调用方应先 `await client.market.reloadMarkets(venue)`，再按 summary 订阅新增 symbol。已加载 venue 上的后台 reload 不会阻塞并发 `subscribe*()`；reload 完成前订阅新增 symbol 仍可能按旧目录返回 `MARKET_NOT_FOUND`。
+
 `MarketDefinition` 见 [§9](#9-数据类型参考)。价格/数量相关字段（`priceStep`、`amountStep`、`contractSize`、`minAmount`、`minNotional`）都是 canonical decimal string；需要运算时用 `new BigNumber(field)` 自行解析。
 
 归一化下单价格和数量：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.4.0-beta.5",
+  "version": "0.4.0-beta.6",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "repository": {
     "type": "git",

package/src/managers/market-manager.ts

@@ -23,6 +23,7 @@ import type {
   FundingRateUpdatedEvent,
   L1Book,
   L1BookUpdatedEvent,
+  MarketCatalogReloadSummary,
   MarketDataStatus,
   MarketDataStreamStatus,
   MarketDefinition,
@@ -63,6 +64,13 @@ interface MarketRecord {
   fundingRateStream?: StreamHandle;
 }
 
+interface CatalogFetchResult {
+  venue: Venue;
+  added: string[];
+  removed: string[];
+  total: number;
+}
+
 const DEFAULT_INITIAL_L1_TIMEOUT_MS = 15_000;
 const DEFAULT_L1_STALE_AFTER_MS = 15_000;
 const DEFAULT_L1_RECONNECT_DELAY_MS = 1_000;
@@ -114,7 +122,10 @@ export class MarketManagerImpl
   private readonly definitions = new Map<string, MarketDefinition>();
   private readonly records = new Map<string, MarketRecord>();
   private readonly loadedCatalogVenues = new Set<Venue>();
-  private readonly catalogPromises = new Map<Venue, Promise<void>>();
+  private readonly catalogPromises = new Map<
+    Venue,
+    Promise<CatalogFetchResult>
+  >();
   private readonly initialL1TimeoutMs: number;
   private readonly l1StaleAfterMs: number;
   private readonly l1ReconnectDelayMs: number;
@@ -166,6 +177,30 @@ export class MarketManagerImpl
     );
   }
 
+  async reloadMarkets(venue?: Venue): Promise<MarketCatalogReloadSummary[]> {
+    if (venue !== undefined) {
+      this.assertSupportedVenue(venue);
+      return [await this.reloadVenue(venue)];
+    }
+
+    const venues = [...this.adapters.keys()];
+    const settled = await Promise.allSettled(
+      venues.map((registeredVenue) => this.reloadVenue(registeredVenue)),
+    );
+    const summaries: MarketCatalogReloadSummary[] = [];
+
+    for (const result of settled) {
+      if (result.status === "fulfilled") {
+        summaries.push(result.value);
+        continue;
+      }
+
+      throw result.reason;
+    }
+
+    return summaries;
+  }
+
   async subscribeL1Book(input: SubscribeL1BookInput): Promise<void> {
     this.context.assertStarted();
     const market = await this.resolveMarketDefinition(input);
@@ -438,51 +473,132 @@ export class MarketManagerImpl
       return;
     }
 
-    let catalogPromise = this.catalogPromises.get(venue);
-    if (!catalogPromise) {
-      catalogPromise = this.fetchAndStoreMarketCatalog(venue);
-      this.catalogPromises.set(venue, catalogPromise);
-    }
+    await this.fetchCatalogCoalesced(venue);
+  }
 
+  private async reloadVenue(venue: Venue): Promise<MarketCatalogReloadSummary> {
     try {
-      await catalogPromise;
+      const result = await this.fetchCatalogCoalesced(venue);
+      return { ...result, ok: true };
     } catch (error) {
-      this.catalogPromises.delete(venue);
+      if (
+        error instanceof AcexError &&
+        error.code === "MARKET_CATALOG_LOAD_FAILED"
+      ) {
+        return {
+          venue,
+          added: [],
+          removed: [],
+          total: this.countVenueMarkets(venue),
+          ok: false,
+          error,
+        };
+      }
+
       throw error;
     }
   }
 
-  private async fetchAndStoreMarketCatalog(venue: Venue): Promise<void> {
+  private async fetchCatalogCoalesced(
+    venue: Venue,
+  ): Promise<CatalogFetchResult> {
+    let catalogPromise = this.catalogPromises.get(venue);
+    if (!catalogPromise) {
+      catalogPromise = this.fetchAndStoreMarketCatalog(venue).finally(() => {
+        this.catalogPromises.delete(venue);
+      });
+      this.catalogPromises.set(venue, catalogPromise);
+    }
+
+    return await catalogPromise;
+  }
+
+  private async fetchAndStoreMarketCatalog(
+    venue: Venue,
+  ): Promise<CatalogFetchResult> {
     const adapter = this.getMarketAdapter(venue);
+    let markets: MarketDefinition[];
 
     try {
-      const markets = await adapter.loadMarkets();
+      markets = await adapter.loadMarkets();
+    } catch (error) {
+      throw this.createCatalogLoadError(venue, error);
+    }
 
-      for (const [key, market] of this.definitions) {
-        if (market.venue === venue) {
-          this.definitions.delete(key);
-        }
-      }
+    const mismatchedMarket = markets.find((market) => market.venue !== venue);
+    if (mismatchedMarket) {
+      throw this.createCatalogLoadError(
+        venue,
+        new Error(
+          `Market catalog from ${venue} included ${mismatchedMarket.venue} market: ${mismatchedMarket.symbol}`,
+        ),
+      );
+    }
+
+    const previousKeys = this.getVenueMarketKeys(venue);
 
-      for (const market of markets) {
-        this.definitions.set(marketKey(market), market);
+    for (const [key, market] of this.definitions) {
+      if (market.venue === venue) {
+        this.definitions.delete(key);
       }
+    }
 
-      this.loadedCatalogVenues.add(venue);
-    } catch (error) {
-      const wrapped = new AcexError(
-        "MARKET_CATALOG_LOAD_FAILED",
-        `Failed to load market catalog from ${venue}`,
-      );
-      this.context.publishRuntimeError(
-        "adapter",
-        error instanceof Error
-          ? error
-          : new Error("Unknown catalog load failure"),
-        { venue },
-      );
-      throw wrapped;
+    for (const market of markets) {
+      this.definitions.set(marketKey(market), market);
     }
+
+    this.loadedCatalogVenues.add(venue);
+
+    const currentKeys = this.getVenueMarketKeys(venue);
+    return {
+      venue,
+      added: this.diffMarketSymbols(venue, currentKeys, previousKeys),
+      removed: this.diffMarketSymbols(venue, previousKeys, currentKeys),
+      total: currentKeys.size,
+    };
+  }
+
+  private getVenueMarketKeys(venue: Venue): Set<string> {
+    const keys = new Set<string>();
+
+    for (const [key, market] of this.definitions) {
+      if (market.venue === venue) {
+        keys.add(key);
+      }
+    }
+
+    return keys;
+  }
+
+  private countVenueMarkets(venue: Venue): number {
+    return this.getVenueMarketKeys(venue).size;
+  }
+
+  private diffMarketSymbols(
+    venue: Venue,
+    left: Set<string>,
+    right: Set<string>,
+  ): string[] {
+    const prefix = `${venue}:`;
+    return [...left]
+      .filter((key) => !right.has(key))
+      .map((key) => key.slice(prefix.length))
+      .sort((leftSymbol, rightSymbol) => leftSymbol.localeCompare(rightSymbol));
+  }
+
+  private createCatalogLoadError(venue: Venue, error: unknown): AcexError {
+    const wrapped = new AcexError(
+      "MARKET_CATALOG_LOAD_FAILED",
+      `Failed to load market catalog from ${venue}`,
+    );
+    this.context.publishRuntimeError(
+      "adapter",
+      error instanceof Error
+        ? error
+        : new Error("Unknown catalog load failure"),
+      { venue },
+    );
+    return wrapped;
   }
 
   private async resolveMarketDefinition(input: {

package/src/types/market.ts

@@ -1,4 +1,5 @@
 import type BigNumber from "bignumber.js";
+import type { AcexError } from "../errors.ts";
 import type { MarketFreshness, SubscriptionActivity, Venue } from "./shared.ts";
 
 export type MarketType = "spot" | "swap" | "future";
@@ -26,6 +27,15 @@ export interface MarketDefinition {
   raw: Record<string, unknown>;
 }
 
+export interface MarketCatalogReloadSummary {
+  venue: Venue;
+  added: string[];
+  removed: string[];
+  total: number;
+  ok: boolean;
+  error?: AcexError;
+}
+
 export interface MarketDataStatus {
   venue: Venue;
   symbol: string;
@@ -159,6 +169,7 @@ export interface MarketManager {
   readonly events: MarketEventStreams;
 
   loadMarkets(): Promise<void>;
+  reloadMarkets(venue?: Venue): Promise<MarketCatalogReloadSummary[]>;
   subscribeL1Book(input: SubscribeL1BookInput): Promise<void>;
   unsubscribeL1Book(input: SubscribeL1BookInput): Promise<void>;
   subscribeFundingRate(input: SubscribeFundingRateInput): Promise<void>;