@datarecce/ui 0.1.29 → 0.1.31

package/recce-source/js/src/lib/api/keepAlive.ts

@@ -0,0 +1,108 @@
+import { AxiosInstance } from "axios";
+import { axiosClient } from "./axiosClient";
+
+/**
+ * Check if debug logging is enabled via window.RECCE_DEBUG_IDLE
+ */
+function isDebugEnabled(): boolean {
+  // biome-ignore lint/suspicious/noExplicitAny: window flag for debug logging
+  return typeof window !== "undefined" && !!(window as any).RECCE_DEBUG_IDLE;
+}
+
+/**
+ * Minimum interval between keep-alive API calls (3 seconds)
+ * This prevents excessive API calls while still maintaining responsive idle detection
+ */
+const MIN_KEEP_ALIVE_INTERVAL_MS = 3 * 1000;
+
+/**
+ * State for axios-layer throttling
+ * - lastKeepAliveTime: timestamp of last SUCCESSFUL keep-alive sent to server
+ * - isSending: lock to prevent concurrent API calls
+ */
+let lastKeepAliveTime = 0;
+let isSending = false;
+
+/** Callback to notify listeners when keep-alive is successfully sent */
+type KeepAliveCallback = (timestamp: number) => void;
+let onKeepAliveSuccess: KeepAliveCallback | null = null;
+
+/**
+ * Register a callback to be notified when keep-alive is successfully sent
+ * Used by IdleTimeoutContext to track server sync time
+ */
+export function setKeepAliveCallback(callback: KeepAliveCallback | null): void {
+  onKeepAliveSuccess = callback;
+}
+
+/**
+ * Send a keep-alive signal to the server to reset the idle timeout timer.
+ * This prevents the server from shutting down due to inactivity.
+ *
+ * Includes built-in throttling at the axios layer:
+ * - Minimum 3 seconds between API calls
+ * - Prevents concurrent API calls with a lock
+ *
+ * @param client - Optional axios instance for API configuration
+ * @returns true if keep-alive was sent, false if throttled/skipped
+ */
+export async function sendKeepAlive(
+  client: AxiosInstance = axiosClient,
+): Promise<boolean> {
+  const now = Date.now();
+  const elapsed = now - lastKeepAliveTime;
+
+  // Throttle: skip if called within minimum interval
+  if (elapsed < MIN_KEEP_ALIVE_INTERVAL_MS) {
+    return false;
+  }
+
+  // Prevent concurrent sends
+  if (isSending) {
+    return false;
+  }
+
+  try {
+    // Acquire lock inside try to ensure finally always releases it
+    isSending = true;
+    await client.post("/api/keep-alive");
+    // Update timestamp only on SUCCESS
+    lastKeepAliveTime = Date.now();
+    // Notify listeners
+    if (onKeepAliveSuccess) {
+      onKeepAliveSuccess(lastKeepAliveTime);
+    }
+    return true;
+  } catch (error) {
+    // Silent fail - don't disrupt user experience if keep-alive fails
+    if (isDebugEnabled()) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      console.log("[Keep-Alive] Failed to send", {
+        error: errorMessage,
+        timestamp: new Date().toISOString(),
+        willRetryOnNextActivity: true,
+      });
+    }
+    return false;
+  } finally {
+    isSending = false;
+  }
+}
+
+/**
+ * Get the last successful keep-alive timestamp
+ * This represents the last time the server confirmed it received our keep-alive
+ */
+export function getLastKeepAliveTime(): number {
+  return lastKeepAliveTime;
+}
+
+/**
+ * Reset all module state (for testing purposes)
+ */
+export function resetKeepAliveState(): void {
+  lastKeepAliveTime = 0;
+  isSending = false;
+  onKeepAliveSuccess = null;
+}

package/recce-source/js/src/lib/api/lineagecheck.ts

@@ -0,0 +1,35 @@
+import { AxiosInstance, AxiosResponse } from "axios";
+import { axiosClient } from "./axiosClient";
+import { Check } from "./checks";
+import { CllInput } from "./cll";
+
+export interface LineageDiffViewOptions {
+  view_mode?: "changed_models" | "all";
+  node_ids?: string[];
+  packages?: string[];
+  select?: string;
+  exclude?: string;
+  column_level_lineage?: CllInput;
+}
+
+interface CreateLineageDiffCheckBody {
+  type: string;
+  params: Record<string, string | boolean | number>;
+  view_options: LineageDiffViewOptions;
+}
+
+export async function createLineageDiffCheck(
+  viewOptions: LineageDiffViewOptions,
+  client: AxiosInstance = axiosClient,
+): Promise<Check> {
+  const response = await client.post<
+    CreateLineageDiffCheckBody,
+    AxiosResponse<Check>
+  >("/api/checks", {
+    type: "lineage_diff",
+    params: {},
+    view_options: viewOptions,
+  });
+
+  return response.data;
+}

package/recce-source/js/src/lib/api/localStorageKeys.ts

@@ -0,0 +1,7 @@
+const prefix = "recce-";
+
+export const localStorageKeys = {
+  bypassSaveOverwrite: `${prefix}-bypass-save-overwrite`,
+  previewChangeFeedbackID: `${prefix}-preview-change-feedback`,
+  prepareEnvGuideID: `${prefix}-prepare-env`,
+};

package/recce-source/js/src/lib/api/models.ts

@@ -0,0 +1,59 @@
+import { AxiosInstance } from "axios";
+import { axiosClient } from "./axiosClient";
+import { RowCountDiffResult, submitRowCountDiff } from "./rowcount";
+import { waitRun } from "./runs";
+
+export interface RowCount {
+  name?: string;
+  curr: number | null;
+}
+
+export interface RowCountDiff {
+  name?: string;
+  base: number | null;
+  curr: number | null;
+}
+
+export interface QueryRowCountResult {
+  runId: string;
+  result: RowCountDiffResult;
+}
+
+export async function fetchModelRowCount(
+  modelName: string,
+  client: AxiosInstance = axiosClient,
+): Promise<RowCountDiff> {
+  const response = await client.get<RowCountDiff>(
+    `/api/models/${modelName}/row_count`,
+  );
+  return response.data;
+}
+
+export async function queryModelRowCount(
+  modelName: string,
+  client: AxiosInstance = axiosClient,
+): Promise<RowCountDiff> {
+  const { result } = await queryRowCount([modelName], client);
+  return result[modelName];
+}
+
+export async function queryRowCount(
+  modelNames: string[],
+  client: AxiosInstance = axiosClient,
+): Promise<QueryRowCountResult> {
+  if (modelNames.length === 0) {
+    throw new Error("No model names provided");
+  }
+
+  const { run_id } = await submitRowCountDiff(
+    { node_names: modelNames },
+    { nowait: true },
+    client,
+  );
+  const run = await waitRun(run_id, undefined, client);
+
+  return {
+    runId: run_id,
+    result: run.result as RowCountDiffResult,
+  };
+}

package/recce-source/js/src/lib/api/profile.ts

@@ -0,0 +1,65 @@
+import { AxiosInstance } from "axios";
+import { axiosClient } from "./axiosClient";
+import { SubmitOptions, submitRun } from "./runs";
+import { ColumnRenderMode, DataFrame } from "./types";
+
+export interface ProfileDiffParams {
+  model: string;
+  columns?: string[];
+}
+
+export interface ProfileDiffResult {
+  base?: DataFrame;
+  current?: DataFrame;
+}
+
+export interface ProfileDiffViewOptions {
+  pinned_columns?: string[];
+  display_mode?: "side_by_side" | "inline";
+  columnsRenderMode?: Record<string, ColumnRenderMode>;
+}
+
+export async function submitProfileDiff(
+  params: ProfileDiffParams,
+  options?: SubmitOptions,
+  client: AxiosInstance = axiosClient,
+) {
+  return await submitRun("profile_diff", params, options, client);
+}
+
+export interface TopKDiffParams {
+  model: string;
+  column_name: string;
+  k: number;
+}
+
+export interface TopKResult {
+  values: (string | number | undefined)[];
+  counts: number[];
+  valids: number;
+}
+
+export interface TopKDiffResult {
+  base: TopKResult;
+  current: TopKResult;
+}
+
+export interface HistogramDiffParams {
+  model: string;
+  column_name: string;
+  column_type: string;
+}
+
+export interface HistogramResult {
+  counts: number[];
+  total: number;
+}
+
+export interface HistogramDiffResult {
+  base: HistogramResult;
+  current: HistogramResult;
+  min: number;
+  max: number;
+  bin_edges: number[];
+  labels?: string[];
+}

package/recce-source/js/src/lib/api/rowcount.ts

@@ -0,0 +1,19 @@
+import { AxiosInstance } from "axios";
+import { axiosClient } from "./axiosClient";
+import { RowCount, RowCountDiff } from "./models";
+import { SubmitOptions, submitRun } from "./runs";
+export interface RowCountParams {
+  node_names: string[];
+}
+export type RowCountResult = Record<string, RowCount>;
+export interface RowCountDiffParams {
+  node_names: string[];
+}
+export type RowCountDiffResult = Record<string, RowCountDiff>;
+export async function submitRowCountDiff(
+  params: RowCountDiffParams,
+  options?: SubmitOptions,
+  client: AxiosInstance = axiosClient,
+) {
+  return await submitRun("row_count_diff", params, options, client);
+}

package/recce-source/js/src/lib/api/runs.ts

@@ -0,0 +1,174 @@
+import { AxiosInstance, AxiosResponse } from "axios";
+import { RunType } from "@/components/run/registry";
+import { axiosClient } from "./axiosClient";
+import { getExperimentTrackingBreakingChangeEnabled } from "./track";
+import { AxiosQueryParams, isQueryRun, Run, RunParamTypes } from "./types";
+
+export interface SubmitRunTrackProps {
+  breaking_change_analysis?: boolean;
+  source?: "lineage_model_node" | "lineage_column_node";
+  [key: string]: unknown;
+}
+
+export interface SubmitOptions {
+  nowait?: boolean;
+  trackProps?: SubmitRunTrackProps;
+}
+
+interface SubmitRunBody {
+  type: RunType;
+  params?: Record<string, unknown>;
+  nowait?: boolean;
+  track_props: SubmitRunTrackProps;
+}
+
+function mutateAddKey(run: Run): Run {
+  if (run.result == null) {
+    // no result, don't do anything
+    return run;
+  }
+  if (isQueryRun(run)) {
+    run.result.columns = run.result.columns.map((c) => {
+      if (c.key) {
+        return c;
+      }
+      c.key = c.name;
+      return c;
+    });
+  }
+  return run;
+}
+
+export async function submitRun(
+  type: RunType,
+  params?: RunParamTypes,
+  options?: SubmitOptions,
+  client: AxiosInstance = axiosClient,
+) {
+  const track_props = options?.trackProps ? { ...options.trackProps } : {};
+  if (getExperimentTrackingBreakingChangeEnabled()) {
+    track_props.breaking_change_analysis = true;
+  }
+
+  const response = await client.post<
+    SubmitRunBody,
+    AxiosResponse<Run | Pick<Run, "run_id">>
+  >("/api/runs", {
+    type,
+    params,
+    nowait: options?.nowait,
+    track_props,
+  });
+
+  return response.data;
+}
+
+export async function getRun(
+  runId: string,
+  client: AxiosInstance = axiosClient,
+) {
+  const response = await client.get<never, AxiosResponse<Run>>(
+    `/api/runs/${runId}`,
+  );
+  return response.data;
+}
+
+interface WaitRunBody {
+  params: {
+    timeout?: number;
+  };
+}
+
+export async function waitRun(
+  runId: string,
+  timeout?: number,
+  client: AxiosInstance = axiosClient,
+) {
+  const response = await client.get<WaitRunBody, AxiosResponse<Run>>(
+    `/api/runs/${runId}/wait`,
+    {
+      params: {
+        timeout,
+      },
+    },
+  );
+
+  return mutateAddKey(response.data);
+}
+
+export async function cancelRun(
+  runId: string,
+  client: AxiosInstance = axiosClient,
+) {
+  return await client.post<never, AxiosResponse<never>>(
+    `/api/runs/${runId}/cancel`,
+  );
+}
+
+export async function submitRunFromCheck(
+  checkId: string,
+  options?: SubmitOptions,
+  client: AxiosInstance = axiosClient,
+) {
+  const response = await client.post<
+    { nowait?: boolean },
+    AxiosResponse<Run | Pick<Run, "run_id">>
+  >(`/api/checks/${checkId}/run`, {
+    nowait: options?.nowait,
+  });
+
+  return response.data;
+}
+
+interface SearchRunsBody {
+  type: string;
+  params: Record<string, unknown>;
+  limit?: number;
+}
+
+export async function searchRuns(
+  type: string,
+  params?: AxiosQueryParams,
+  limit?: number,
+  client: AxiosInstance = axiosClient,
+) {
+  const response = await client.post<SearchRunsBody, AxiosResponse<Run[]>>(
+    `/api/runs/search`,
+    {
+      type,
+      params,
+      limit,
+    },
+  );
+
+  return response.data;
+}
+
+export async function listRuns(
+  client: AxiosInstance = axiosClient,
+): Promise<Run[]> {
+  const response = await client.get<never, AxiosResponse<Run[]>>("/api/runs");
+  return response.data;
+}
+
+export type RunsAggregated = Record<
+  string,
+  Record<
+    "row_count_diff" | "value_diff" | "row_count",
+    {
+      run_id: string;
+      result: unknown;
+    }
+  >
+>;
+export async function aggregateRuns(
+  client: AxiosInstance = axiosClient,
+): Promise<RunsAggregated> {
+  // input should be AggregateRunsIn
+  const response = await client.post<unknown, AxiosResponse<RunsAggregated>>(
+    `/api/runs/aggregate`,
+    {},
+  );
+
+  return response.data;
+}

package/recce-source/js/src/lib/api/schemacheck.ts

@@ -0,0 +1,31 @@
+import { AxiosInstance, AxiosResponse } from "axios";
+import { axiosClient } from "./axiosClient";
+import { Check } from "./checks";
+
+export interface SchemaDiffViewParams {
+  node_id?: string | string[];
+  select?: string;
+  exclude?: string;
+  view_mode?: "all" | "changed_models";
+  packages?: string[];
+}
+
+interface CreateSchemaDiffCheckBody {
+  type: string;
+  params: SchemaDiffViewParams;
+}
+
+export async function createSchemaDiffCheck(
+  params: SchemaDiffViewParams,
+  client: AxiosInstance = axiosClient,
+): Promise<Check> {
+  const response = await client.post<
+    CreateSchemaDiffCheckBody,
+    AxiosResponse<Check>
+  >("/api/checks", {
+    type: "schema_diff",
+    params: params,
+  });
+
+  return response.data;
+}

package/recce-source/js/src/lib/api/select.ts

@@ -0,0 +1,25 @@
+import { AxiosInstance, AxiosResponse } from "axios";
+import { axiosClient } from "./axiosClient";
+
+export interface SelectInput {
+  select?: string;
+  exclude?: string;
+  packages?: string[];
+  view_mode?: "all" | "changed_models";
+}
+
+export interface SelectOutput {
+  nodes: string[];
+}
+
+export async function select(
+  input: SelectInput,
+  client: AxiosInstance = axiosClient,
+): Promise<SelectOutput> {
+  return (
+    await client.post<SelectInput, AxiosResponse<SelectOutput>>(
+      `/api/select`,
+      input,
+    )
+  ).data;
+}

package/recce-source/js/src/lib/api/sessionStorageKeys.ts

@@ -0,0 +1,8 @@
+const prefix = "recce";
+
+export const sessionStorageKeys = {
+  recommendationIgnored: `${prefix}-recommendation-ignored`,
+  recommendationShowed: `${prefix}-recommendation-showed`,
+  prevRefreshTimeStamp: `${prefix}-prev-refresh-timestamp`,
+  lineageNotificationDismissed: `${prefix}-lineage-notification-dismissed`,
+};

package/recce-source/js/src/lib/api/state.ts

@@ -0,0 +1,117 @@
+import { AxiosInstance, AxiosResponse, isAxiosError } from "axios";
+import { axiosClient } from "./axiosClient";
+
+export interface SaveAsInput {
+  filename: string;
+  overwrite?: boolean;
+}
+
+export interface ImportedState {
+  runs: number;
+  checks: number;
+}
+
+export async function saveAs(
+  input: SaveAsInput,
+  client: AxiosInstance = axiosClient,
+): Promise<void> {
+  return (
+    await client.post<SaveAsInput, AxiosResponse<void>>("/api/save-as", input)
+  ).data;
+}
+
+export async function rename(
+  input: SaveAsInput,
+  client: AxiosInstance = axiosClient,
+): Promise<void> {
+  return (
+    await client.post<SaveAsInput, AxiosResponse<void>>("/api/rename", input)
+  ).data;
+}
+
+export async function exportState(
+  client: AxiosInstance = axiosClient,
+): Promise<string> {
+  return (await client.post<never, AxiosResponse<string>>("/api/export")).data;
+}
+
+interface ImportStateBody {
+  file: File;
+  checks_only: "true" | "false";
+}
+
+export async function importState(
+  file: File,
+  checksOnly?: boolean,
+  client: AxiosInstance = axiosClient,
+): Promise<ImportedState> {
+  const formData = new FormData();
+  formData.append("file", file);
+  formData.append("checks_only", (!!checksOnly).toString());
+
+  return (
+    await client.post<ImportStateBody, AxiosResponse<ImportedState>>(
+      "/api/import",
+      formData,
+    )
+  ).data;
+}
+
+export async function isStateSyncing(
+  client: AxiosInstance = axiosClient,
+): Promise<boolean> {
+  const response = await client.get<never, AxiosResponse<boolean>>("/api/sync");
+  return response.status === 208;
+}
+
+export interface SyncStateInput {
+  method?: "overwrite" | "revert" | "merge";
+}
+export interface SyncStateResponse {
+  status: "accepted" | "conflict" | "syncing";
+}
+
+export async function syncState(
+  input: SyncStateInput,
+  client: AxiosInstance = axiosClient,
+): Promise<SyncStateResponse> {
+  try {
+    const response = await client.post<
+      SyncStateInput,
+      AxiosResponse<SyncStateResponse>
+    >("/api/sync", input);
+
+    if (response.status === 202) {
+      return {
+        status: "accepted",
+      };
+    }
+    if (response.status === 208) {
+      return {
+        status: "syncing",
+      };
+    }
+  } catch (error) {
+    if (isAxiosError(error)) {
+      if (error.response?.status === 409) {
+        // 409 conflict case
+        return { status: "conflict" };
+      }
+    }
+  }
+  throw new Error("Failed to sync state");
+}
+
+export interface ShareStateResponse {
+  status: string;
+  message: string;
+  share_url?: string;
+}
+
+export async function shareState(
+  client: AxiosInstance = axiosClient,
+): Promise<ShareStateResponse> {
+  return (
+    await client.post<never, AxiosResponse<ShareStateResponse>>("/api/share")
+  ).data;
+}