@l.x/prices 1.0.3 → 1.0.4

package/.depcheckrc

@@ -0,0 +1,14 @@
+ignores: [
+    # Dependencies that depcheck incorrectly marks as unused
+    "typescript",
+    "@typescript/native-preview",
+    "depcheck",
+
+    # Internal packages / workspaces
+    "prices",
+    "@universe/prices",
+
+    # TODO: remove once used in tests
+    "@testing-library/react",
+    "@vitest/coverage-v8",
+  ]

package/.eslintrc.js

@@ -0,0 +1,20 @@
+module.exports = {
+  extends: ['@luxamm/eslint-config/lib'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+  },
+  overrides: [
+    {
+      files: ['*.ts', '*.tsx'],
+      rules: {
+        'no-relative-import-paths/no-relative-import-paths': [
+          'error',
+          {
+            allowSameFolder: false,
+            prefix: '@luxexchange/prices',
+          },
+        ],
+      },
+    },
+  ],
+}

package/README.md

@@ -0,0 +1,3 @@
+# @universe/prices
+
+// TODO

package/package.json

@@ -1 +1,44 @@
-{"name":"@l.x/prices","version":"1.0.3","description":"LX Exchange - prices","main":"index.js","dependencies":{"@luxexchange/prices":"1.0.3"}}
+{
+  "name": "@l.x/prices",
+  "version": "1.0.4",
+  "dependencies": {
+    "@tanstack/react-query": "5.90.20",
+    "@luxamm/sdk-core": "7.12.3",
+    "@l.x/api": "workspace:^",
+    "@l.x/websocket": "workspace:^",
+    "@luxfi/utilities": "workspace:^"
+  },
+  "peerDependencies": {
+    "react": "19.0.3"
+  },
+  "devDependencies": {
+    "@testing-library/react": "16.3.0",
+    "@types/node": "22.13.1",
+    "@typescript/native-preview": "7.0.0-dev.20260311.1",
+    "@luxfi/eslint-config": "workspace:^",
+    "@vitest/coverage-v8": "3.2.1",
+    "depcheck": "1.4.7",
+    "eslint": "8.57.1",
+    "react": "19.0.3",
+    "typescript": "5.8.3",
+    "vitest": "3.2.1"
+  },
+  "scripts": {
+    "test": "nx test prices",
+    "typecheck": "nx typecheck prices",
+    "typecheck:tsgo": "nx typecheck:tsgo prices",
+    "lint": "nx lint prices",
+    "lint:fix": "nx lint:fix prices",
+    "lint:biome": "nx lint:biome prices",
+    "lint:biome:fix": "nx lint:biome:fix prices",
+    "lint:eslint": "nx lint:eslint prices",
+    "lint:eslint:fix": "nx lint:eslint:fix prices",
+    "check:deps:usage": "nx check:deps:usage prices"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "main": "src/index.ts",
+  "private": false,
+  "sideEffects": false
+}

package/project.json

@@ -0,0 +1,22 @@
+{
+  "name": "@l.x/prices",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "pkgs/prices/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "test": {
+      "command": "vitest run --passWithNoTests",
+      "options": { "cwd": "{projectRoot}" }
+    },
+    "typecheck": {},
+    "typecheck:tsgo": {},
+    "lint:biome": {},
+    "lint:biome:fix": {},
+    "lint:eslint": {},
+    "lint:eslint:fix": {},
+    "lint": {},
+    "lint:fix": {},
+    "check:deps:usage": {}
+  }
+}

package/src/context/PriceServiceContext.test.tsx

@@ -0,0 +1,63 @@
+// @vitest-environment jsdom
+
+import type { QueryClient } from '@tanstack/react-query'
+import { renderHook } from '@testing-library/react'
+import { PriceServiceProvider, usePricesContext } from '@l.x/prices/src/context/PriceServiceContext'
+import type { TokenPriceMessage, TokenSubscriptionParams } from '@l.x/prices/src/types'
+import type { WebSocketClient } from '@l.x/websocket'
+import type { ReactNode } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+
+function createMockWsClient(): WebSocketClient<TokenSubscriptionParams, TokenPriceMessage['data']> {
+  return {
+    isConnected: vi.fn(() => false),
+    getConnectionStatus: vi.fn(() => 'disconnected' as const),
+    getConnectionId: vi.fn(() => null),
+    subscribe: vi.fn(() => vi.fn()),
+    onStatusChange: vi.fn(() => vi.fn()),
+    onConnectionEstablished: vi.fn(() => vi.fn()),
+  }
+}
+
+function createMockQueryClient(): QueryClient {
+  return { setQueryData: vi.fn() } as unknown as QueryClient
+}
+
+describe('PriceServiceContext', () => {
+  it('usePricesContext throws when used outside PriceServiceProvider', () => {
+    expect(() => {
+      renderHook(() => usePricesContext())
+    }).toThrow('usePricesContext must be used within a PriceServiceProvider')
+  })
+
+  it('usePricesContext returns wsClient and queryClient when inside PriceServiceProvider', () => {
+    const mockWsClient = createMockWsClient()
+    const mockQueryClient = createMockQueryClient()
+
+    const wrapper = ({ children }: { children: ReactNode }): ReactNode => (
+      <PriceServiceProvider wsClient={mockWsClient} queryClient={mockQueryClient}>
+        {children}
+      </PriceServiceProvider>
+    )
+
+    const { result } = renderHook(() => usePricesContext(), { wrapper })
+
+    expect(result.current.wsClient).toBe(mockWsClient)
+    expect(result.current.queryClient).toBe(mockQueryClient)
+  })
+
+  it('PriceServiceProvider renders children', () => {
+    const mockWsClient = createMockWsClient()
+    const mockQueryClient = createMockQueryClient()
+
+    const wrapper = ({ children }: { children: ReactNode }): ReactNode => (
+      <PriceServiceProvider wsClient={mockWsClient} queryClient={mockQueryClient}>
+        {children}
+      </PriceServiceProvider>
+    )
+
+    const { result } = renderHook(() => 'rendered', { wrapper })
+
+    expect(result.current).toBe('rendered')
+  })
+})

package/src/context/PriceServiceContext.tsx

@@ -0,0 +1,36 @@
+import type { QueryClient } from '@tanstack/react-query'
+import type { RestPriceBatcher } from '@l.x/prices/src/sources/rest/RestPriceBatcher'
+import type { TokenPriceMessage, TokenSubscriptionParams } from '@l.x/prices/src/types'
+import type { WebSocketClient } from '@l.x/websocket'
+import { createContext, type ReactElement, type ReactNode, useContext, useMemo } from 'react'
+
+interface PricesContextValue {
+  wsClient: WebSocketClient<TokenSubscriptionParams, TokenPriceMessage['data']>
+  queryClient: QueryClient
+  restBatcher?: RestPriceBatcher
+}
+
+const PricesContext = createContext<PricesContextValue | null>(null)
+
+export function PriceServiceProvider({
+  wsClient,
+  queryClient,
+  restBatcher,
+  children,
+}: {
+  wsClient: WebSocketClient<TokenSubscriptionParams, TokenPriceMessage['data']>
+  queryClient: QueryClient
+  restBatcher?: RestPriceBatcher
+  children: ReactNode
+}): ReactElement {
+  const value = useMemo(() => ({ wsClient, queryClient, restBatcher }), [wsClient, queryClient, restBatcher])
+  return <PricesContext.Provider value={value}>{children}</PricesContext.Provider>
+}
+
+export function usePricesContext(): PricesContextValue {
+  const context = useContext(PricesContext)
+  if (!context) {
+    throw new Error('usePricesContext must be used within a PriceServiceProvider')
+  }
+  return context
+}

package/src/hooks/useConnectionStatus.ts

@@ -0,0 +1,11 @@
+import { usePricesContext } from '@l.x/prices/src/context/PriceServiceContext'
+import type { ConnectionStatus } from '@l.x/websocket'
+import { useSyncExternalStore } from 'react'
+
+/**
+ * Hook to get the current WebSocket connection status.
+ */
+export function useConnectionStatus(): ConnectionStatus {
+  const { wsClient } = usePricesContext()
+  return useSyncExternalStore(wsClient.onStatusChange, wsClient.getConnectionStatus, wsClient.getConnectionStatus)
+}

package/src/hooks/usePrice.ts

@@ -0,0 +1,48 @@
+import { queryOptions, skipToken, useQuery, useQueryClient } from '@tanstack/react-query'
+import { usePricesContext } from '@l.x/prices/src/context/PriceServiceContext'
+import { priceKeys } from '@l.x/prices/src/queries/priceKeys'
+import { tokenPriceQueryOptions } from '@l.x/prices/src/queries/tokenPriceQueryOptions'
+import type { TokenPriceData } from '@l.x/prices/src/types'
+import { useEffect } from 'react'
+
+interface UsePriceOptions {
+  chainId: number | undefined
+  address: string | undefined
+  live?: boolean
+}
+
+/**
+ * Hook to get the live price for a token.
+ * Reads from React Query cache and auto-subscribes via websocket.
+ * Falls back to REST polling when WS data goes stale (if restBatcher is provided).
+ *
+ * Requires a PriceServiceProvider in the tree.
+ */
+export function usePrice(options: UsePriceOptions): number | undefined {
+  const { chainId, address, live = true } = options
+  const { wsClient, restBatcher } = usePricesContext()
+  const queryClient = useQueryClient()
+
+  const enabled = chainId !== undefined && !!address
+
+  // Data is populated externally via queryClient.setQueryData from WS messages.
+  // When restBatcher is provided, queryFn fires as a fallback when WS data goes stale.
+  const { data } = useQuery(
+    enabled
+      ? tokenPriceQueryOptions({ chainId, address, restBatcher, queryClient })
+      : queryOptions<TokenPriceData | null>({ queryKey: priceKeys.all, queryFn: skipToken, enabled: false }),
+  )
+
+  useEffect(() => {
+    if (!enabled || !live) {
+      return undefined
+    }
+    return wsClient.subscribe({
+      channel: 'token_price',
+      params: { chainId, tokenAddress: address.toLowerCase() },
+    })
+  }, [enabled, live, chainId, address, wsClient])
+
+  const price: number | undefined = enabled ? (data?.price ?? undefined) : undefined
+  return price
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+// Types
+
+export {
+  isConnectionEstablishedMessage,
+  isRawTokenPriceMessage,
+  parseConnectionMessage,
+  parseTokenPriceMessage,
+} from '@l.x/prices/src/sources/websocket/messageParser'
+// Internals (testing / custom setups)
+export { createPriceSubscriptionHandler } from '@l.x/prices/src/sources/websocket/subscriptionApi'
+export type {
+  ConnectionEstablishedMessage,
+  Logger,
+  PriceKey,
+  RawTokenPriceMessage,
+  TokenIdentifier,
+  TokenInput,
+  TokenPrice,
+  TokenPriceData,
+  TokenPriceMessage,
+  TokenSubscriptionParams,
+} from '@l.x/prices/src/types'
+export {
+  createPriceKey,
+  createPriceKeyFromToken,
+  filterValidTokens,
+  isCurrency,
+  isTokenIdentifier,
+  normalizeToken,
+  parsePriceKey,
+  toSubscriptionParams,
+} from '@l.x/prices/src/utils/tokenIdentifier'
+export type { ConnectionStatus } from '@l.x/websocket'
+export { PriceServiceProvider, usePricesContext } from './context/PriceServiceContext'
+export { useConnectionStatus } from './hooks/useConnectionStatus'
+// Consumer hooks
+// Backward-compat alias
+export { usePrice, usePrice as useLivePrice } from './hooks/usePrice'
+// Query utilities (advanced / UDL)
+export { priceKeys } from './queries/priceKeys'
+export { tokenPriceQueryOptions } from './queries/tokenPriceQueryOptions'
+export { REST_POLL_INTERVAL_MS } from './sources/rest/constants'
+// REST fallback
+export { RestPriceBatcher } from './sources/rest/RestPriceBatcher'
+export type { RestPriceClient } from './sources/rest/types'

package/src/queries/priceKeys.test.ts

@@ -0,0 +1,23 @@
+import { priceKeys } from '@l.x/prices/src/queries/priceKeys'
+import { ReactQueryCacheKey } from 'utilities/src/reactQuery/cache'
+import { describe, expect, it } from 'vitest'
+
+describe('priceKeys', () => {
+  describe('all', () => {
+    it('returns array with TokenPrice cache key', () => {
+      expect(priceKeys.all).toEqual([ReactQueryCacheKey.TokenPrice])
+    })
+  })
+
+  describe('token', () => {
+    it('returns key with chainId and lowercased address', () => {
+      const key = priceKeys.token(1, '0xABC')
+      expect(key).toEqual([ReactQueryCacheKey.TokenPrice, 1, '0xabc'])
+    })
+
+    it('handles already lowercased address', () => {
+      const key = priceKeys.token(42161, '0xdef')
+      expect(key).toEqual([ReactQueryCacheKey.TokenPrice, 42161, '0xdef'])
+    })
+  })
+})

package/src/queries/priceKeys.ts

@@ -0,0 +1,6 @@
+import { ReactQueryCacheKey } from 'utilities/src/reactQuery/cache'
+
+export const priceKeys = {
+  all: [ReactQueryCacheKey.TokenPrice] as const,
+  token: (chainId: number, address: string) => [ReactQueryCacheKey.TokenPrice, chainId, address.toLowerCase()] as const,
+} as const

package/src/queries/tokenPriceQueryOptions.ts

@@ -0,0 +1,41 @@
+import { type QueryClient, queryOptions, skipToken } from '@tanstack/react-query'
+import { priceKeys } from '@l.x/prices/src/queries/priceKeys'
+import { REST_POLL_INTERVAL_MS } from '@l.x/prices/src/sources/rest/constants'
+import type { RestPriceBatcher } from '@l.x/prices/src/sources/rest/RestPriceBatcher'
+import type { TokenPriceData } from '@l.x/prices/src/types'
+
+export interface TokenPriceQueryOptionsParams {
+  chainId: number
+  address: string
+  restBatcher?: RestPriceBatcher
+  queryClient?: QueryClient
+}
+
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function tokenPriceQueryOptions({ chainId, address, restBatcher, queryClient }: TokenPriceQueryOptionsParams) {
+  const key = priceKeys.token(chainId, address)
+  return queryOptions<TokenPriceData | null>({
+    queryKey: key,
+    queryFn: restBatcher
+      ? async (): Promise<TokenPriceData | null> => {
+          const fresh = await restBatcher.fetch({ chainId, address: address.toLowerCase() })
+          if (!fresh) {
+            return null
+          }
+          // Guard against REST responses overwriting newer WebSocket data.
+          // refetchInterval fires independently of staleTime, so without this
+          // check a 30s-old REST response could clobber a sub-second WS update.
+          const existing = queryClient?.getQueryData<TokenPriceData>(key)
+          if (existing && existing.timestamp >= fresh.timestamp) {
+            return existing
+          }
+          return fresh
+        }
+      : skipToken,
+    staleTime: Infinity,
+    refetchOnWindowFocus: false,
+    refetchOnMount: false,
+    structuralSharing: false,
+    refetchInterval: restBatcher ? REST_POLL_INTERVAL_MS : false,
+  })
+}

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' },
+    ])
+  })
+})