@kopai/ui 0.0.4 → 0.1.0

package/src/components/observability/utils/time.ts

@@ -0,0 +1,46 @@
+/**
+ * Time formatting utilities for trace visualization
+ */
+
+export function formatDuration(durationMs: number): string {
+  if (durationMs < 1) {
+    const microseconds = durationMs * 1000;
+    return `${microseconds.toFixed(2)}μs`;
+  } else if (durationMs < 1000) {
+    return `${durationMs.toFixed(2)}ms`;
+  } else {
+    const seconds = durationMs / 1000;
+    return `${seconds.toFixed(2)}s`;
+  }
+}
+
+export function formatTimestamp(timestampMs: number): string {
+  const date = new Date(timestampMs);
+  return date.toLocaleString("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    timeZoneName: "short",
+  });
+}
+
+export function calculateRelativeTime(
+  timeMs: number,
+  minTimeMs: number,
+  maxTimeMs: number
+): number {
+  const totalDuration = maxTimeMs - minTimeMs;
+  if (totalDuration === 0) return 0;
+  return (timeMs - minTimeMs) / totalDuration;
+}
+
+export function calculateRelativeDuration(
+  durationMs: number,
+  totalDurationMs: number
+): number {
+  if (totalDurationMs === 0) return 0;
+  return durationMs / totalDurationMs;
+}

package/src/hooks/use-kopai-data.test.ts

@@ -0,0 +1,296 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { createElement, type ReactNode } from "react";
+import { useKopaiData } from "./use-kopai-data.js";
+import {
+  KopaiSDKProvider,
+  queryClient,
+  type KopaiClient,
+} from "../providers/kopai-provider.js";
+import type { DataSource } from "../lib/component-catalog.js";
+
+const createMockClient = () => ({
+  searchTracesPage: vi.fn(),
+  searchLogsPage: vi.fn(),
+  searchMetricsPage: vi.fn(),
+  getTrace: vi.fn(),
+  discoverMetrics: vi.fn(),
+});
+
+type MockClient = ReturnType<typeof createMockClient>;
+
+function wrapper(client: KopaiClient) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return createElement(KopaiSDKProvider, { client, children });
+  };
+}
+
+describe("useKopaiData", () => {
+  let mockClient: MockClient;
+
+  beforeEach(() => {
+    mockClient = createMockClient();
+    queryClient.clear();
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("initial state", () => {
+    it("returns null data when no dataSource", () => {
+      const { result } = renderHook(() => useKopaiData(undefined), {
+        wrapper: wrapper(mockClient),
+      });
+
+      expect(result.current.data).toBeNull();
+      expect(result.current.loading).toBe(false);
+      expect(result.current.error).toBeNull();
+    });
+  });
+
+  describe("searchTracesPage", () => {
+    it("fetches traces and updates state", async () => {
+      const mockData = { data: [{ traceId: "123" }], nextCursor: null };
+      mockClient.searchTracesPage.mockResolvedValue(mockData);
+
+      const dataSource: DataSource = {
+        method: "searchTracesPage",
+        params: { serviceName: "test-service" },
+      };
+
+      const { result } = renderHook(() => useKopaiData(dataSource), {
+        wrapper: wrapper(mockClient),
+      });
+
+      expect(result.current.loading).toBe(true);
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.data).toEqual(mockData);
+      expect(result.current.error).toBeNull();
+      expect(mockClient.searchTracesPage).toHaveBeenCalledWith(
+        { serviceName: "test-service" },
+        expect.objectContaining({ signal: expect.any(AbortSignal) })
+      );
+    });
+
+    it("handles errors", async () => {
+      const error = new Error("Network error");
+      mockClient.searchTracesPage.mockRejectedValue(error);
+
+      const dataSource: DataSource = {
+        method: "searchTracesPage",
+        params: {},
+      };
+
+      const { result } = renderHook(() => useKopaiData(dataSource), {
+        wrapper: wrapper(mockClient),
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.error).toEqual(error);
+      expect(result.current.data).toBeNull();
+    });
+  });
+
+  describe("searchLogsPage", () => {
+    it("fetches logs", async () => {
+      const mockData = { data: [{ body: "log entry" }], nextCursor: null };
+      mockClient.searchLogsPage.mockResolvedValue(mockData);
+
+      const dataSource: DataSource = {
+        method: "searchLogsPage",
+        params: { serviceName: "test-service" },
+      };
+
+      const { result } = renderHook(() => useKopaiData(dataSource), {
+        wrapper: wrapper(mockClient),
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.data).toEqual(mockData);
+      expect(mockClient.searchLogsPage).toHaveBeenCalled();
+    });
+  });
+
+  describe("searchMetricsPage", () => {
+    it("fetches metrics", async () => {
+      const mockData = { data: [{ metricName: "cpu" }], nextCursor: null };
+      mockClient.searchMetricsPage.mockResolvedValue(mockData);
+
+      const dataSource: DataSource = {
+        method: "searchMetricsPage",
+        params: { metricType: "Gauge" },
+      };
+
+      const { result } = renderHook(() => useKopaiData(dataSource), {
+        wrapper: wrapper(mockClient),
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.data).toEqual(mockData);
+      expect(mockClient.searchMetricsPage).toHaveBeenCalled();
+    });
+  });
+
+  describe("getTrace", () => {
+    it("fetches single trace", async () => {
+      const mockData = [{ traceId: "abc", spanId: "123" }];
+      mockClient.getTrace.mockResolvedValue(mockData);
+
+      const dataSource: DataSource = {
+        method: "getTrace",
+        params: { traceId: "abc" },
+      };
+
+      const { result } = renderHook(() => useKopaiData(dataSource), {
+        wrapper: wrapper(mockClient),
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.data).toEqual(mockData);
+      expect(mockClient.getTrace).toHaveBeenCalledWith(
+        "abc",
+        expect.objectContaining({ signal: expect.any(AbortSignal) })
+      );
+    });
+  });
+
+  describe("discoverMetrics", () => {
+    it("discovers metrics", async () => {
+      const mockData = { metrics: [{ name: "cpu_usage", type: "Gauge" }] };
+      mockClient.discoverMetrics.mockResolvedValue(mockData);
+
+      const dataSource: DataSource = {
+        method: "discoverMetrics",
+        params: {},
+      };
+
+      const { result } = renderHook(() => useKopaiData(dataSource), {
+        wrapper: wrapper(mockClient),
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.data).toEqual(mockData);
+      expect(mockClient.discoverMetrics).toHaveBeenCalled();
+    });
+  });
+
+  describe("refetch", () => {
+    it("refetches same query on refetch()", async () => {
+      const mockData1 = { data: [{ id: "1" }], nextCursor: "cursor1" };
+      const mockData2 = { data: [{ id: "2" }], nextCursor: null };
+      mockClient.searchTracesPage
+        .mockResolvedValueOnce(mockData1)
+        .mockResolvedValueOnce(mockData2);
+
+      const dataSource: DataSource = {
+        method: "searchTracesPage",
+        params: { limit: 10 },
+      };
+
+      const { result } = renderHook(() => useKopaiData(dataSource), {
+        wrapper: wrapper(mockClient),
+      });
+
+      await waitFor(() => {
+        expect(result.current.data).toEqual(mockData1);
+      });
+
+      act(() => {
+        result.current.refetch();
+      });
+
+      await waitFor(() => {
+        expect(result.current.data).toEqual(mockData2);
+      });
+
+      expect(mockClient.searchTracesPage).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("dataSource change", () => {
+    it("triggers new fetch when dataSource changes", async () => {
+      const tracesData = { data: [{ traceId: "t1" }] };
+      const logsData = { data: [{ body: "log1" }] };
+      mockClient.searchTracesPage.mockResolvedValue(tracesData);
+      mockClient.searchLogsPage.mockResolvedValue(logsData);
+
+      const { result, rerender } = renderHook(
+        ({ ds }: { ds: DataSource }) => useKopaiData(ds),
+        {
+          wrapper: wrapper(mockClient),
+          initialProps: {
+            ds: { method: "searchTracesPage", params: {} } as DataSource,
+          },
+        }
+      );
+
+      await waitFor(() => {
+        expect(result.current.data).toEqual(tracesData);
+      });
+
+      rerender({
+        ds: { method: "searchLogsPage", params: {} } as DataSource,
+      });
+
+      await waitFor(() => {
+        expect(result.current.data).toEqual(logsData);
+      });
+
+      expect(mockClient.searchTracesPage).toHaveBeenCalledTimes(1);
+      expect(mockClient.searchLogsPage).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("cleanup", () => {
+    it("cancels in-flight request on unmount", async () => {
+      let abortSignal: AbortSignal | undefined;
+      mockClient.searchTracesPage.mockImplementation(
+        async (_: unknown, opts?: { signal?: AbortSignal }) => {
+          abortSignal = opts?.signal;
+          return new Promise(() => {});
+        }
+      );
+
+      const dataSource: DataSource = {
+        method: "searchTracesPage",
+        params: {},
+      };
+
+      const { unmount } = renderHook(() => useKopaiData(dataSource), {
+        wrapper: wrapper(mockClient),
+      });
+
+      await waitFor(() => {
+        expect(abortSignal).toBeDefined();
+      });
+
+      unmount();
+
+      expect(abortSignal?.aborted).toBe(true);
+    });
+  });
+});

package/src/hooks/use-kopai-data.ts

@@ -0,0 +1,64 @@
+import { useQuery } from "@tanstack/react-query";
+import type { DataSource } from "../lib/component-catalog.js";
+import { useKopaiSDK } from "../providers/kopai-provider.js";
+
+export interface UseKopaiDataResult<T> {
+  data: T | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+function fetchForDataSource(
+  client: ReturnType<typeof useKopaiSDK>,
+  dataSource: DataSource,
+  signal: AbortSignal
+): Promise<unknown> {
+  switch (dataSource.method) {
+    case "searchTracesPage":
+      return client.searchTracesPage(
+        dataSource.params as Parameters<typeof client.searchTracesPage>[0],
+        { signal }
+      );
+    case "searchLogsPage":
+      return client.searchLogsPage(
+        dataSource.params as Parameters<typeof client.searchLogsPage>[0],
+        { signal }
+      );
+    case "searchMetricsPage":
+      return client.searchMetricsPage(
+        dataSource.params as Parameters<typeof client.searchMetricsPage>[0],
+        { signal }
+      );
+    case "getTrace":
+      return client.getTrace(dataSource.params.traceId, { signal });
+    case "discoverMetrics":
+      return client.discoverMetrics({ signal });
+    default: {
+      const exhaustiveCheck: never = dataSource;
+      throw new Error(
+        `Unknown method: ${(exhaustiveCheck as DataSource).method}`
+      );
+    }
+  }
+}
+
+export function useKopaiData<T = unknown>(
+  dataSource: DataSource | undefined
+): UseKopaiDataResult<T> {
+  const client = useKopaiSDK();
+
+  const { data, isFetching, error, refetch } = useQuery<unknown, Error>({
+    queryKey: ["kopai", dataSource?.method, dataSource?.params],
+    queryFn: ({ signal }) => fetchForDataSource(client, dataSource!, signal),
+    enabled: !!dataSource,
+    refetchInterval: dataSource?.refetchIntervalMs,
+  });
+
+  return {
+    data: (data as T) ?? null,
+    loading: isFetching,
+    error: error ?? null,
+    refetch,
+  };
+}

package/src/hooks/use-live-logs.test.ts

@@ -0,0 +1,193 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { createElement, type ReactNode } from "react";
+import { useLiveLogs } from "./use-live-logs.js";
+import {
+  KopaiSDKProvider,
+  queryClient,
+  type KopaiClient,
+} from "../providers/kopai-provider.js";
+
+const BASE_NS = 1700000000000000000n;
+const ts = (offsetMs: number) =>
+  (BASE_NS + BigInt(offsetMs) * 1000000n).toString();
+
+const createMockClient = () => ({
+  searchTracesPage: vi.fn(),
+  searchLogsPage: vi.fn(),
+  searchMetricsPage: vi.fn(),
+  getTrace: vi.fn(),
+  discoverMetrics: vi.fn(),
+});
+
+function wrapper(client: KopaiClient) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return createElement(KopaiSDKProvider, { client, children });
+  };
+}
+
+describe("useLiveLogs", () => {
+  let mockClient: ReturnType<typeof createMockClient>;
+
+  beforeEach(() => {
+    mockClient = createMockClient();
+    queryClient.clear();
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("fetches and returns logs on initial load", async () => {
+    const batch = [
+      {
+        Timestamp: ts(100),
+        Body: "log1",
+        ServiceName: "svc",
+        SeverityNumber: 9,
+      },
+      {
+        Timestamp: ts(200),
+        Body: "log2",
+        ServiceName: "svc",
+        SeverityNumber: 9,
+      },
+    ];
+
+    mockClient.searchLogsPage.mockResolvedValue({
+      data: batch,
+      nextCursor: null,
+    });
+
+    const { result } = renderHook(
+      () =>
+        useLiveLogs({
+          params: { limit: 200 },
+          pollIntervalMs: 60_000, // long interval so no refetch during test
+        }),
+      { wrapper: wrapper(mockClient) }
+    );
+
+    await waitFor(() => {
+      expect(result.current.logs).toHaveLength(2);
+    });
+
+    expect(result.current.totalReceived).toBe(2);
+    expect(result.current.isLive).toBe(true);
+    expect(result.current.error).toBeNull();
+
+    // First call should not have timestampMin
+    const firstCall = mockClient.searchLogsPage.mock.calls[0]![0];
+    expect(firstCall.timestampMin).toBeUndefined();
+  });
+
+  it("uses timestampMin on manual refetch after first load", async () => {
+    mockClient.searchLogsPage
+      .mockResolvedValueOnce({
+        data: [
+          {
+            Timestamp: ts(100),
+            Body: "log1",
+            ServiceName: "svc",
+            SeverityNumber: 9,
+          },
+        ],
+        nextCursor: null,
+      })
+      .mockResolvedValueOnce({
+        data: [
+          {
+            Timestamp: ts(300),
+            Body: "log3",
+            ServiceName: "svc",
+            SeverityNumber: 9,
+          },
+        ],
+        nextCursor: null,
+      });
+
+    const { result } = renderHook(
+      () =>
+        useLiveLogs({
+          params: { limit: 200 },
+          pollIntervalMs: 600_000,
+        }),
+      { wrapper: wrapper(mockClient) }
+    );
+
+    // Wait for first fetch
+    await waitFor(() => {
+      expect(result.current.logs).toHaveLength(1);
+    });
+
+    // Pause then resume to trigger refetch
+    act(() => {
+      result.current.setLive(false);
+    });
+    act(() => {
+      result.current.setLive(true);
+    });
+
+    await waitFor(
+      () => {
+        expect(
+          mockClient.searchLogsPage.mock.calls.length
+        ).toBeGreaterThanOrEqual(2);
+      },
+      { timeout: 3000 }
+    );
+
+    // The refetch call(s) after first should have timestampMin
+    const calls = mockClient.searchLogsPage.mock.calls;
+    const expectedMin = String(BigInt(ts(100)) + 1n);
+    const callsWithTimestampMin = calls.filter(
+      (c: unknown[]) =>
+        (c[0] as Record<string, unknown>).timestampMin !== undefined
+    );
+    expect(callsWithTimestampMin.length).toBeGreaterThan(0);
+    expect(callsWithTimestampMin[0]![0].timestampMin).toBe(expectedMin);
+  });
+
+  it("setLive(false) sets isLive to false", async () => {
+    mockClient.searchLogsPage.mockResolvedValue({ data: [], nextCursor: null });
+
+    const { result } = renderHook(
+      () =>
+        useLiveLogs({
+          params: { limit: 200 },
+          pollIntervalMs: 600_000,
+        }),
+      { wrapper: wrapper(mockClient) }
+    );
+
+    await waitFor(() => {
+      expect(result.current.loading).toBe(false);
+    });
+
+    expect(result.current.isLive).toBe(true);
+
+    act(() => {
+      result.current.setLive(false);
+    });
+
+    expect(result.current.isLive).toBe(false);
+  });
+
+  it("starts as live by default", async () => {
+    mockClient.searchLogsPage.mockResolvedValue({ data: [], nextCursor: null });
+
+    const { result } = renderHook(
+      () =>
+        useLiveLogs({
+          params: { limit: 200 },
+        }),
+      { wrapper: wrapper(mockClient) }
+    );
+
+    expect(result.current.isLive).toBe(true);
+  });
+});

package/src/hooks/use-live-logs.ts

@@ -0,0 +1,113 @@
+import { useState, useRef, useCallback, useEffect } from "react";
+import { useQuery } from "@tanstack/react-query";
+import type { denormalizedSignals, dataFilterSchemas } from "@kopai/core";
+import { useKopaiSDK } from "../providers/kopai-provider.js";
+import { LogBuffer } from "../lib/log-buffer.js";
+
+type OtelLogsRow = denormalizedSignals.OtelLogsRow;
+type LogsDataFilter = dataFilterSchemas.LogsDataFilter;
+
+export interface UseLiveLogsOptions {
+  params: LogsDataFilter;
+  pollIntervalMs?: number;
+  maxLogs?: number;
+  enabled?: boolean;
+}
+
+export interface UseLiveLogsResult {
+  logs: OtelLogsRow[];
+  isLive: boolean;
+  totalReceived: number;
+  loading: boolean;
+  error: Error | null;
+  setLive: (live: boolean) => void;
+}
+
+export function useLiveLogs({
+  params,
+  pollIntervalMs = 3_000,
+  maxLogs = 1_000,
+  enabled = true,
+}: UseLiveLogsOptions): UseLiveLogsResult {
+  const client = useKopaiSDK();
+  const bufferRef = useRef(new LogBuffer(maxLogs));
+  const [version, setVersion] = useState(0);
+  const [isLive, setIsLiveState] = useState(true);
+  const totalReceivedRef = useRef(0);
+  const hasFetchedOnce = useRef(false);
+
+  // Reset buffer when params change so stale data from a previous filter
+  // doesn't persist while the new query is in flight.
+  const paramsKey = JSON.stringify(params);
+  const prevParamsKey = useRef(paramsKey);
+  useEffect(() => {
+    if (prevParamsKey.current !== paramsKey) {
+      prevParamsKey.current = paramsKey;
+      bufferRef.current.clear();
+      hasFetchedOnce.current = false;
+      totalReceivedRef.current = 0;
+      setVersion((v) => v + 1);
+    }
+  }, [paramsKey]);
+
+  const { isFetching, error, refetch } = useQuery<
+    { data: OtelLogsRow[]; nextCursor: string | null },
+    Error
+  >({
+    queryKey: ["live-logs", params],
+    queryFn: async ({ signal }) => {
+      const fetchParams: LogsDataFilter = { ...params };
+
+      // If params changed since queryFn was scheduled, treat as first fetch
+      if (prevParamsKey.current !== JSON.stringify(params)) {
+        hasFetchedOnce.current = false;
+      }
+
+      // After first fetch, only get newer logs
+      if (hasFetchedOnce.current) {
+        const newest = bufferRef.current.getNewestTimestamp();
+        if (newest) {
+          // Add 1ns to avoid re-fetching the same row
+          fetchParams.timestampMin = String(BigInt(newest) + 1n);
+        }
+      }
+
+      const result = await client.searchLogsPage(fetchParams, { signal });
+      hasFetchedOnce.current = true;
+
+      if (result.data.length > 0) {
+        totalReceivedRef.current += result.data.length;
+        bufferRef.current.merge(result.data);
+        setVersion((v) => v + 1);
+      }
+
+      return result;
+    },
+    enabled: enabled,
+    refetchInterval: isLive ? pollIntervalMs : false,
+  });
+
+  const setLive = useCallback(
+    (live: boolean) => {
+      setIsLiveState(live);
+      if (live) {
+        // Immediate refetch on resume
+        refetch();
+      }
+    },
+    [refetch]
+  );
+
+  // Read buffer (version forces re-render)
+  void version;
+  const logs = bufferRef.current.getAll();
+
+  return {
+    logs,
+    isLive,
+    totalReceived: totalReceivedRef.current,
+    loading: isFetching,
+    error: error ?? null,
+    setLive,
+  };
+}