@l.x/prices 1.0.3 → 1.0.5

package/src/sources/rest/RestPriceBatcher.test.ts

@@ -0,0 +1,223 @@
+import { BATCH_DELAY_MS, MAX_BATCH_SIZE } from '@l.x/prices/src/sources/rest/constants'
+import { RestPriceBatcher } from '@l.x/prices/src/sources/rest/RestPriceBatcher'
+import type { RestPriceClient } from '@l.x/prices/src/sources/rest/types'
+import type { TokenPriceData } from '@l.x/prices/src/types'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+function createMockClient(
+  handler: (tokens: { chainId: number; address: string }[]) => Promise<Map<string, TokenPriceData>>,
+): RestPriceClient {
+  return { getTokenPrices: vi.fn(handler) }
+}
+
+function priceData(price: number, timestamp = Date.now()): TokenPriceData {
+  return { price, timestamp }
+}
+
+describe('RestPriceBatcher', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('batches multiple fetch calls within the batching window', async () => {
+    const client = createMockClient(async (tokens) => {
+      const result = new Map<string, TokenPriceData>()
+      for (const t of tokens) {
+        result.set(`${t.chainId}-${t.address}`, priceData(100 + t.chainId))
+      }
+      return result
+    })
+
+    const batcher = new RestPriceBatcher(client)
+
+    // Fire multiple fetches synchronously (same batching window)
+    const p1 = batcher.fetch({ chainId: 1, address: '0xaaa' })
+    const p2 = batcher.fetch({ chainId: 42161, address: '0xbbb' })
+
+    // Advance past the batch delay to trigger flush
+    vi.advanceTimersByTime(BATCH_DELAY_MS)
+
+    const [r1, r2] = await Promise.all([p1, p2])
+
+    expect(r1).toEqual(priceData(101, r1!.timestamp))
+    expect(r2).toEqual(priceData(42261, r2!.timestamp))
+    expect(client.getTokenPrices).toHaveBeenCalledTimes(1)
+    expect(client.getTokenPrices).toHaveBeenCalledWith([
+      { chainId: 1, address: '0xaaa' },
+      { chainId: 42161, address: '0xbbb' },
+    ])
+  })
+
+  it('deduplicates tokens within the same batch', async () => {
+    const client = createMockClient(async (tokens) => {
+      const result = new Map<string, TokenPriceData>()
+      for (const t of tokens) {
+        result.set(`${t.chainId}-${t.address}`, priceData(50))
+      }
+      return result
+    })
+
+    const batcher = new RestPriceBatcher(client)
+
+    const p1 = batcher.fetch({ chainId: 1, address: '0xAAA' })
+    const p2 = batcher.fetch({ chainId: 1, address: '0xaaa' }) // Same after lowercase
+
+    vi.advanceTimersByTime(BATCH_DELAY_MS)
+
+    const [r1, r2] = await Promise.all([p1, p2])
+
+    expect(r1).toEqual(priceData(50, r1!.timestamp))
+    expect(r2).toEqual(priceData(50, r2!.timestamp))
+    // Only 1 unique token sent to the client
+    expect(client.getTokenPrices).toHaveBeenCalledWith([{ chainId: 1, address: '0xaaa' }])
+  })
+
+  it('chunks large batches to respect MAX_BATCH_SIZE', async () => {
+    const client = createMockClient(async (tokens) => {
+      const result = new Map<string, TokenPriceData>()
+      for (const t of tokens) {
+        result.set(`${t.chainId}-${t.address}`, priceData(1))
+      }
+      return result
+    })
+
+    const batcher = new RestPriceBatcher(client)
+
+    // Create MAX_BATCH_SIZE + 10 unique tokens
+    const count = MAX_BATCH_SIZE + 10
+    const promises = Array.from({ length: count }, (_, i) =>
+      batcher.fetch({ chainId: 1, address: `0x${i.toString(16).padStart(40, '0')}` }),
+    )
+
+    vi.advanceTimersByTime(BATCH_DELAY_MS)
+
+    const results = await Promise.all(promises)
+
+    expect(results).toHaveLength(count)
+    expect(results.every((r) => r !== undefined)).toBe(true)
+    // Should have been split into 2 REST calls
+    expect(client.getTokenPrices).toHaveBeenCalledTimes(2)
+  })
+
+  it('propagates errors to all pending promises', async () => {
+    const error = new Error('network failure')
+    const client = createMockClient(async () => {
+      throw error
+    })
+
+    const batcher = new RestPriceBatcher(client)
+
+    const p1 = batcher.fetch({ chainId: 1, address: '0xaaa' })
+    const p2 = batcher.fetch({ chainId: 42161, address: '0xbbb' })
+
+    vi.advanceTimersByTime(BATCH_DELAY_MS)
+
+    await expect(p1).rejects.toThrow('network failure')
+    await expect(p2).rejects.toThrow('network failure')
+  })
+
+  it('returns undefined for tokens not in REST response', async () => {
+    const client = createMockClient(async () => {
+      // Return empty map (no prices available)
+      return new Map<string, TokenPriceData>()
+    })
+
+    const batcher = new RestPriceBatcher(client)
+
+    const promise = batcher.fetch({ chainId: 1, address: '0xaaa' })
+
+    vi.advanceTimersByTime(BATCH_DELAY_MS)
+
+    const result = await promise
+
+    expect(result).toBeUndefined()
+  })
+
+  it('processes sequential batches independently', async () => {
+    let callCount = 0
+    const client = createMockClient(async (tokens) => {
+      callCount++
+      const result = new Map<string, TokenPriceData>()
+      for (const t of tokens) {
+        result.set(`${t.chainId}-${t.address}`, priceData(callCount * 100))
+      }
+      return result
+    })
+
+    const batcher = new RestPriceBatcher(client)
+
+    // First batch
+    const p1 = batcher.fetch({ chainId: 1, address: '0xaaa' })
+    vi.advanceTimersByTime(BATCH_DELAY_MS)
+    const r1 = await p1
+    expect(r1?.price).toBe(100)
+
+    // Second batch (new timer window)
+    const p2 = batcher.fetch({ chainId: 1, address: '0xbbb' })
+    vi.advanceTimersByTime(BATCH_DELAY_MS)
+    const r2 = await p2
+    expect(r2?.price).toBe(200)
+
+    expect(client.getTokenPrices).toHaveBeenCalledTimes(2)
+  })
+
+  it('lowercases addresses for deduplication', async () => {
+    const client = createMockClient(async (tokens) => {
+      const result = new Map<string, TokenPriceData>()
+      for (const t of tokens) {
+        result.set(`${t.chainId}-${t.address}`, priceData(42))
+      }
+      return result
+    })
+
+    const batcher = new RestPriceBatcher(client)
+
+    const promise = batcher.fetch({ chainId: 1, address: '0xAbCdEf' })
+
+    vi.advanceTimersByTime(BATCH_DELAY_MS)
+
+    const result = await promise
+
+    expect(result?.price).toBe(42)
+    expect(client.getTokenPrices).toHaveBeenCalledWith([{ chainId: 1, address: '0xabcdef' }])
+  })
+
+  it('batches requests arriving in separate macrotasks within the delay window', async () => {
+    const client = createMockClient(async (tokens) => {
+      const result = new Map<string, TokenPriceData>()
+      for (const t of tokens) {
+        result.set(`${t.chainId}-${t.address}`, priceData(99))
+      }
+      return result
+    })
+
+    const batcher = new RestPriceBatcher(client)
+
+    // First request starts the timer
+    const p1 = batcher.fetch({ chainId: 1, address: '0xaaa' })
+
+    // Advance partway through the delay (simulating a second macrotask arriving)
+    vi.advanceTimersByTime(BATCH_DELAY_MS / 2)
+
+    // Second request arrives before the timer fires
+    const p2 = batcher.fetch({ chainId: 10, address: '0xbbb' })
+
+    // Now advance past the delay to flush
+    vi.advanceTimersByTime(BATCH_DELAY_MS)
+
+    const [r1, r2] = await Promise.all([p1, p2])
+
+    expect(r1?.price).toBe(99)
+    expect(r2?.price).toBe(99)
+    // Both should be in a single batch
+    expect(client.getTokenPrices).toHaveBeenCalledTimes(1)
+    expect(client.getTokenPrices).toHaveBeenCalledWith([
+      { chainId: 1, address: '0xaaa' },
+      { chainId: 10, address: '0xbbb' },
+    ])
+  })
+})

package/src/sources/rest/RestPriceBatcher.ts

@@ -0,0 +1,110 @@
+import { BATCH_DELAY_MS, MAX_BATCH_SIZE } from '@l.x/prices/src/sources/rest/constants'
+import type { RestPriceClient } from '@l.x/prices/src/sources/rest/types'
+import type { TokenIdentifier, TokenPriceData } from '@l.x/prices/src/types'
+import { createPriceKey } from '@l.x/prices/src/utils/tokenIdentifier'
+
+interface PendingRequest {
+  token: TokenIdentifier
+  resolve: (value: TokenPriceData | undefined) => void
+  reject: (error: unknown) => void
+}
+
+/**
+ * Timer-based batcher for REST price fetches.
+ *
+ * Individual `fetch(token)` calls are coalesced into a single batch REST
+ * request within a short delay window (BATCH_DELAY_MS ≈ one frame). This
+ * ensures requests from separate macrotasks (e.g. React Query refetchInterval
+ * callbacks) are grouped together. Duplicate tokens share the same result.
+ * Batches exceeding MAX_BATCH_SIZE are chunked into parallel requests.
+ */
+export class RestPriceBatcher {
+  private readonly client: RestPriceClient
+  private pending: PendingRequest[] = []
+  private flushTimer: ReturnType<typeof setTimeout> | null = null
+
+  constructor(client: RestPriceClient) {
+    this.client = client
+  }
+
+  /**
+   * Request a price for a single token. Multiple calls within the same
+   * batching window (BATCH_DELAY_MS) are batched into one REST request.
+   *
+   * @returns The price data, or undefined if the token has no price.
+   */
+  fetch(token: TokenIdentifier): Promise<TokenPriceData | undefined> {
+    return new Promise<TokenPriceData | undefined>((resolve, reject) => {
+      this.pending.push({
+        token: { chainId: token.chainId, address: token.address.toLowerCase() },
+        resolve,
+        reject,
+      })
+
+      if (this.flushTimer === null) {
+        this.flushTimer = setTimeout(() => this.flush(), BATCH_DELAY_MS)
+      }
+    })
+  }
+
+  private async flush(): Promise<void> {
+    const batch = this.pending
+    this.pending = []
+    this.flushTimer = null
+
+    if (batch.length === 0) {
+      return
+    }
+
+    // Group resolvers by price key (deduplication)
+    const resolversByKey = new Map<string, PendingRequest[]>()
+    const uniqueTokens = new Map<string, TokenIdentifier>()
+
+    for (const request of batch) {
+      const key = createPriceKey(request.token.chainId, request.token.address)
+      const existing = resolversByKey.get(key)
+      if (existing) {
+        existing.push(request)
+      } else {
+        resolversByKey.set(key, [request])
+        uniqueTokens.set(key, request.token)
+      }
+    }
+
+    const tokens = Array.from(uniqueTokens.values())
+
+    // Chunk into batches of MAX_BATCH_SIZE
+    const chunks: TokenIdentifier[][] = []
+    for (let i = 0; i < tokens.length; i += MAX_BATCH_SIZE) {
+      chunks.push(tokens.slice(i, i + MAX_BATCH_SIZE))
+    }
+
+    try {
+      // Fetch all chunks in parallel
+      const results = await Promise.all(chunks.map((chunk) => this.client.getTokenPrices(chunk)))
+
+      // Merge all chunk results
+      const merged = new Map<string, TokenPriceData>()
+      for (const chunkResult of results) {
+        for (const [key, value] of chunkResult) {
+          merged.set(key, value)
+        }
+      }
+
+      // Resolve all pending requests
+      for (const [key, requests] of resolversByKey) {
+        const data = merged.get(key)
+        for (const request of requests) {
+          request.resolve(data)
+        }
+      }
+    } catch (error) {
+      // On error, reject all pending promises (React Query retries individually)
+      for (const requests of resolversByKey.values()) {
+        for (const request of requests) {
+          request.reject(error)
+        }
+      }
+    }
+  }
+}

package/src/sources/rest/constants.ts

@@ -0,0 +1,9 @@
+/** How often to poll REST as a fallback for fresh prices */
+export const REST_POLL_INTERVAL_MS = 30_000
+
+/** Maximum tokens per REST request (backend limit) */
+export const MAX_BATCH_SIZE = 100
+
+/** Delay before flushing a batch (~one frame). Allows requests from separate
+ *  macrotasks (e.g. React Query refetchInterval callbacks) to be grouped. */
+export const BATCH_DELAY_MS = 16

package/src/sources/rest/types.ts

@@ -0,0 +1,13 @@
+import type { TokenIdentifier, TokenPriceData } from '@l.x/prices/src/types'
+
+/**
+ * Contract for fetching token prices via REST.
+ * Implementations handle the actual transport (ConnectRPC, fetch, etc.).
+ */
+export interface RestPriceClient {
+  /**
+   * Fetches prices for a batch of tokens.
+   * @returns Map keyed by price key ("chainId-address"), missing tokens omitted.
+   */
+  getTokenPrices(tokens: TokenIdentifier[]): Promise<Map<string, TokenPriceData>>
+}

package/src/sources/websocket/messageParser.ts

@@ -0,0 +1,79 @@
+import type { ConnectionEstablishedMessage, RawTokenPriceMessage, TokenPriceMessage } from '@l.x/prices/src/types'
+import { createPriceKey } from '@l.x/prices/src/utils/tokenIdentifier'
+
+/**
+ * Type guard for RawTokenPriceMessage
+ */
+export function isRawTokenPriceMessage(message: unknown): message is RawTokenPriceMessage {
+  return (
+    typeof message === 'object' &&
+    message !== null &&
+    'type' in message &&
+    message.type === 'token_price_update' &&
+    'payload' in message &&
+    typeof message.payload === 'object' &&
+    message.payload !== null
+  )
+}
+
+/**
+ * Type guard for ConnectionEstablishedMessage
+ */
+export function isConnectionEstablishedMessage(message: unknown): message is ConnectionEstablishedMessage {
+  return (
+    typeof message === 'object' &&
+    message !== null &&
+    'connectionEstablished' in message &&
+    typeof message.connectionEstablished === 'object' &&
+    message.connectionEstablished !== null &&
+    'connectionId' in message.connectionEstablished
+  )
+}
+
+/**
+ * Parses a raw WebSocket message into a typed price update.
+ * Returns null if the message is not a price update.
+ *
+ * Used both as the `parseMessage` config for createWebSocketClient
+ * and in the `onRawMessage` callback to write to React Query cache.
+ */
+export function parseTokenPriceMessage(raw: unknown): TokenPriceMessage | null {
+  if (!isRawTokenPriceMessage(raw)) {
+    return null
+  }
+
+  const { chainId, tokenAddress, priceUsd } = raw.payload
+  const price = parseFloat(priceUsd)
+
+  if (Number.isNaN(price)) {
+    return null
+  }
+
+  const timestamp = new Date(raw.timestamp).getTime()
+  const key = createPriceKey(chainId, tokenAddress)
+
+  return {
+    channel: 'token_price',
+    key,
+    data: {
+      chainId,
+      tokenAddress: tokenAddress.toLowerCase(),
+      priceUsd: price,
+      timestamp,
+    },
+  }
+}
+
+/**
+ * Parses a raw WebSocket message for connection establishment.
+ * Returns null if the message is not a connection message.
+ */
+export function parseConnectionMessage(raw: unknown): { connectionId: string } | null {
+  if (!isConnectionEstablishedMessage(raw)) {
+    return null
+  }
+
+  return {
+    connectionId: raw.connectionEstablished.connectionId,
+  }
+}

package/src/sources/websocket/subscriptionApi.ts

@@ -0,0 +1,105 @@
+import type { FetchClient } from '@l.x/api'
+import type { TokenSubscriptionParams } from '@l.x/prices/src/types'
+import type { SubscriptionHandler } from '@l.x/websocket'
+
+const EVENT_SUBSCRIPTION_TYPE_TOKEN_PRICE = 'EVENT_SUBSCRIPTION_TYPE_TOKEN_PRICE'
+
+export interface SubscriptionApiOptions {
+  client: FetchClient
+  onError?: (error: unknown, operation: string) => void
+}
+
+/**
+ * Creates a subscription handler for token price subscriptions.
+ * This implements the SubscriptionHandler interface from @l.x/websocket.
+ */
+export function createPriceSubscriptionHandler(
+  options: SubscriptionApiOptions,
+): SubscriptionHandler<TokenSubscriptionParams> {
+  const { client, onError } = options
+
+  async function subscribe(connectionId: string, params: TokenSubscriptionParams): Promise<void> {
+    try {
+      await client.post('/lx.notificationservice.v1.EventSubscriptionService/Subscribe', {
+        body: JSON.stringify({
+          eventSubscriptionType: EVENT_SUBSCRIPTION_TYPE_TOKEN_PRICE,
+          connectionId,
+          events: [{ token: { chainId: params.chainId, tokenAddress: params.tokenAddress } }],
+        }),
+      })
+    } catch (error) {
+      onError?.(error, 'subscribe')
+    }
+  }
+
+  async function unsubscribe(connectionId: string, params: TokenSubscriptionParams): Promise<void> {
+    try {
+      await client.post('/lx.notificationservice.v1.EventSubscriptionService/Unsubscribe', {
+        body: JSON.stringify({
+          eventSubscriptionType: EVENT_SUBSCRIPTION_TYPE_TOKEN_PRICE,
+          connectionId,
+          events: [{ token: { chainId: params.chainId, tokenAddress: params.tokenAddress } }],
+        }),
+      })
+    } catch (error) {
+      onError?.(error, 'unsubscribe')
+    }
+  }
+
+  async function subscribeBatch(connectionId: string, paramsList: TokenSubscriptionParams[]): Promise<void> {
+    if (paramsList.length === 0) {
+      return
+    }
+
+    try {
+      await client.post('/lx.notificationservice.v1.EventSubscriptionService/Subscribe', {
+        body: JSON.stringify({
+          eventSubscriptionType: EVENT_SUBSCRIPTION_TYPE_TOKEN_PRICE,
+          connectionId,
+          events: paramsList.map((p) => ({ token: { chainId: p.chainId, tokenAddress: p.tokenAddress } })),
+        }),
+      })
+    } catch (error) {
+      onError?.(error, 'subscribeBatch')
+    }
+  }
+
+  async function unsubscribeBatch(connectionId: string, paramsList: TokenSubscriptionParams[]): Promise<void> {
+    if (paramsList.length === 0) {
+      return
+    }
+
+    try {
+      await client.post('/lx.notificationservice.v1.EventSubscriptionService/Unsubscribe', {
+        body: JSON.stringify({
+          eventSubscriptionType: EVENT_SUBSCRIPTION_TYPE_TOKEN_PRICE,
+          connectionId,
+          events: paramsList.map((p) => ({ token: { chainId: p.chainId, tokenAddress: p.tokenAddress } })),
+        }),
+      })
+    } catch (error) {
+      onError?.(error, 'unsubscribeBatch')
+    }
+  }
+
+  async function refreshSession(connectionId: string): Promise<void> {
+    try {
+      await client.post('/lx.notificationservice.v1.EventSubscriptionService/RefreshSession', {
+        body: JSON.stringify({
+          eventSubscriptionType: EVENT_SUBSCRIPTION_TYPE_TOKEN_PRICE,
+          connectionId,
+        }),
+      })
+    } catch (error) {
+      onError?.(error, 'refreshSession')
+    }
+  }
+
+  return {
+    subscribe,
+    unsubscribe,
+    subscribeBatch,
+    unsubscribeBatch,
+    refreshSession,
+  }
+}

package/src/types.ts

@@ -0,0 +1,96 @@
+import type { Currency } from '@luxamm/sdk-core'
+
+/**
+ * A token identifier with chain and address.
+ * Can be used instead of a full Currency object.
+ */
+export interface TokenIdentifier {
+  chainId: number
+  address: string
+}
+
+/**
+ * Token price data with timestamp.
+ */
+export interface TokenPrice {
+  price: number
+  timestamp: number
+}
+
+/**
+ * Shape stored in the React Query cache for each token price.
+ */
+export interface TokenPriceData {
+  price: number
+  timestamp: number
+}
+
+/**
+ * Key used to identify a token price in the store.
+ * Format: "chainId-address" (e.g., "1-0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2")
+ * Matches CurrencyId convention from lx/src/utils/currencyId.ts
+ */
+export type PriceKey = string
+
+/**
+ * Token identifier format used by the subscription API.
+ */
+export interface TokenSubscriptionParams {
+  chainId: number
+  tokenAddress: string
+}
+
+/**
+ * Parsed WebSocket message for token price updates.
+ * Wraps channel, key, and the inner data payload.
+ */
+export interface TokenPriceMessage {
+  channel: string
+  key: string
+  data: {
+    chainId: number
+    tokenAddress: string
+    priceUsd: number
+    timestamp: number
+  }
+}
+
+/**
+ * Raw WebSocket message format from server (strings, optional fields).
+ * Parsed into {@link TokenPriceMessage} by messageParser before app consumption.
+ */
+export interface RawTokenPriceMessage {
+  type: 'token_price_update'
+  payload: {
+    chainId: number
+    tokenAddress: string
+    priceUsd: string
+    symbol?: string
+    timestamp?: string
+  }
+  timestamp: string
+}
+
+/**
+ * Connection established message from server.
+ */
+export interface ConnectionEstablishedMessage {
+  connectionEstablished: {
+    connectionId: string
+    timestamp: string
+  }
+}
+
+/**
+ * Logger interface for optional logging.
+ */
+export interface Logger {
+  debug: (tag: string, context: string, message: string, data?: unknown) => void
+  warn: (tag: string, context: string, message: string, data?: unknown) => void
+  error: (tag: string, context: string, message: string, data?: unknown) => void
+}
+
+/**
+ * Type guard input - any token that can provide chain and address.
+ */
+export type TokenInput = TokenIdentifier | Currency