@buoy-gg/events 2.1.1

package/src/utils/eventTransformers.ts

@@ -0,0 +1,567 @@
+/**
+ * Event Transformers
+ *
+ * Transform events from each source into the unified UnifiedEvent format.
+ *
+ * Note: These transformers use generic types to avoid hard dependencies
+ * on tool packages. The actual transformation logic is in autoDiscoverEventSources.ts.
+ * This file is kept for backwards compatibility and type exports.
+ */
+
+import type { UnifiedEvent, EventStatus } from "../types";
+
+let eventIdCounter = 0;
+
+/**
+ * Generate a unique event ID
+ */
+function generateEventId(source: string): string {
+  return `${source}-${Date.now()}-${++eventIdCounter}`;
+}
+
+// ============================================================================
+// Storage Event Types (for backwards compatibility)
+// ============================================================================
+
+/**
+ * AsyncStorage event action types
+ */
+export type AsyncStorageAction =
+  | "setItem"
+  | "removeItem"
+  | "mergeItem"
+  | "clear"
+  | "multiSet"
+  | "multiRemove"
+  | "multiMerge";
+
+/**
+ * Generic AsyncStorage event structure
+ */
+export interface AsyncStorageEvent {
+  action: AsyncStorageAction;
+  timestamp: Date;
+  data?: {
+    key?: string;
+    value?: unknown;
+    pairs?: Array<[string, unknown]>;
+    keys?: string[];
+  };
+}
+
+/**
+ * Generic Storage event (AsyncStorage or MMKV)
+ */
+export interface StorageEvent {
+  storageType: "async" | "mmkv";
+  action: string;
+  timestamp: Date;
+  data?: {
+    key?: string;
+    value?: unknown;
+    instanceId?: string;
+    pairs?: Array<[string, unknown]>;
+    keys?: string[];
+  };
+}
+
+/**
+ * Get human-readable action name for AsyncStorage events
+ */
+function getAsyncStorageActionLabel(action: AsyncStorageAction): string {
+  switch (action) {
+    case "setItem":
+      return "Set Item";
+    case "removeItem":
+      return "Remove Item";
+    case "mergeItem":
+      return "Merge Item";
+    case "clear":
+      return "Clear All";
+    case "multiSet":
+      return "Multi Set";
+    case "multiRemove":
+      return "Multi Remove";
+    case "multiMerge":
+      return "Multi Merge";
+    default:
+      return action;
+  }
+}
+
+/**
+ * Get subtitle for AsyncStorage event
+ */
+function getAsyncStorageSubtitle(event: AsyncStorageEvent): string {
+  const { action, data } = event;
+
+  switch (action) {
+    case "setItem":
+    case "removeItem":
+    case "mergeItem":
+      return data?.key || "unknown key";
+
+    case "multiSet":
+    case "multiMerge": {
+      const pairCount = data?.pairs?.length || 0;
+      return `${pairCount} key${pairCount !== 1 ? "s" : ""}`;
+    }
+
+    case "multiRemove": {
+      const keyCount = data?.keys?.length || 0;
+      return `${keyCount} key${keyCount !== 1 ? "s" : ""}`;
+    }
+
+    case "clear":
+      return "all keys";
+
+    default:
+      return "";
+  }
+}
+
+/**
+ * Get status for storage event based on action type
+ */
+function getStorageStatus(action: string): EventStatus {
+  if (action.includes("set") || action.includes("Set") || action.includes("merge") || action.includes("Merge")) {
+    return "success";
+  }
+  if (action.includes("remove") || action.includes("Remove") || action === "clear" || action === "delete") {
+    return "neutral";
+  }
+  return "neutral";
+}
+
+/**
+ * Transform StorageEvent (AsyncStorage or MMKV) to UnifiedEvent
+ */
+export function transformStorageEvent(event: StorageEvent): UnifiedEvent {
+  if (event.storageType === "async") {
+    const asyncEvent = event as AsyncStorageEvent & { storageType: "async" };
+    return {
+      id: generateEventId("async"),
+      source: "storage-async",
+      timestamp: asyncEvent.timestamp.getTime(),
+      title: getAsyncStorageActionLabel(asyncEvent.action),
+      subtitle: getAsyncStorageSubtitle(asyncEvent),
+      status: getStorageStatus(asyncEvent.action),
+      originalEvent: asyncEvent,
+    };
+  } else {
+    const mmkvEvent = event as StorageEvent & { storageType: "mmkv" };
+    return {
+      id: generateEventId("mmkv"),
+      source: "storage-mmkv",
+      timestamp: mmkvEvent.timestamp.getTime(),
+      title: mmkvEvent.action,
+      subtitle: mmkvEvent.data?.key || mmkvEvent.data?.instanceId || "unknown",
+      status: getStorageStatus(mmkvEvent.action),
+      originalEvent: mmkvEvent,
+    };
+  }
+}
+
+/**
+ * Legacy export for backwards compatibility
+ */
+export function transformAsyncStorageEvent(event: AsyncStorageEvent): UnifiedEvent {
+  return transformStorageEvent({ ...event, storageType: "async" });
+}
+
+// ============================================================================
+// Redux Event Types
+// ============================================================================
+
+/**
+ * Generic Redux action structure
+ */
+export interface ReduxAction {
+  id: string;
+  type: string;
+  timestamp: number;
+  category?: "fulfilled" | "rejected" | "pending";
+  hasStateChange?: boolean;
+  payloadPreview?: string;
+  diffSummary?: string;
+  duration?: number;
+  sliceName?: string;
+}
+
+/**
+ * Get status for Redux action based on category
+ */
+function getReduxStatus(action: ReduxAction): EventStatus {
+  switch (action.category) {
+    case "fulfilled":
+      return "success";
+    case "rejected":
+      return "error";
+    case "pending":
+      return "pending";
+    default:
+      return action.hasStateChange ? "success" : "neutral";
+  }
+}
+
+/**
+ * Get subtitle for Redux action
+ */
+function getReduxSubtitle(action: ReduxAction): string {
+  if (action.payloadPreview) {
+    return action.payloadPreview;
+  }
+  if (action.hasStateChange && action.diffSummary) {
+    return action.diffSummary;
+  }
+  if (action.duration !== undefined) {
+    return `${action.duration.toFixed(1)}ms`;
+  }
+  return action.sliceName || "";
+}
+
+/**
+ * Transform ReduxAction to UnifiedEvent
+ */
+export function transformReduxAction(action: ReduxAction): UnifiedEvent {
+  return {
+    id: generateEventId("redux"),
+    source: "redux",
+    timestamp: action.timestamp,
+    title: action.type,
+    subtitle: getReduxSubtitle(action),
+    status: getReduxStatus(action),
+    originalEvent: action,
+  };
+}
+
+// ============================================================================
+// Network Event Types
+// ============================================================================
+
+/**
+ * Generic Network event structure
+ */
+export interface NetworkEvent {
+  id: string;
+  method: string;
+  url: string;
+  path?: string;
+  host?: string;
+  status?: number;
+  error?: unknown;
+  duration?: number;
+  timestamp: number;
+  operationName?: string;
+}
+
+/**
+ * Get status for network event based on HTTP status code
+ */
+function getNetworkStatus(event: NetworkEvent): EventStatus {
+  if (event.status === undefined) {
+    return "pending";
+  }
+  if (event.error || event.status >= 400) {
+    return "error";
+  }
+  if (event.status >= 200 && event.status < 400) {
+    return "success";
+  }
+  return "neutral";
+}
+
+/**
+ * Get title for network event
+ */
+function getNetworkTitle(event: NetworkEvent): string {
+  if (event.operationName) {
+    return event.operationName;
+  }
+  return `${event.method} ${event.path || event.url}`;
+}
+
+/**
+ * Get subtitle for network event
+ */
+function getNetworkSubtitle(event: NetworkEvent): string {
+  const parts: string[] = [];
+
+  if (event.status !== undefined) {
+    parts.push(`${event.status}`);
+  } else if (event.error) {
+    parts.push("Error");
+  } else {
+    parts.push("Pending");
+  }
+
+  if (event.duration !== undefined) {
+    parts.push(`${event.duration.toFixed(0)}ms`);
+  }
+
+  if (event.host) {
+    parts.push(event.host);
+  }
+
+  return parts.join(" · ");
+}
+
+/**
+ * Transform NetworkEvent to UnifiedEvent
+ */
+export function transformNetworkEvent(event: NetworkEvent): UnifiedEvent {
+  return {
+    id: generateEventId("network"),
+    source: "network",
+    timestamp: event.timestamp,
+    title: getNetworkTitle(event),
+    subtitle: getNetworkSubtitle(event),
+    status: getNetworkStatus(event),
+    originalEvent: event,
+  };
+}
+
+// ============================================================================
+// React Query Event Types
+// ============================================================================
+
+/**
+ * Generic React Query event structure
+ */
+export interface ReactQueryEvent {
+  id: string;
+  type: string;
+  timestamp: number;
+  queryKey?: unknown[];
+  mutationKey?: unknown[];
+  mutationId?: number;
+  queryHash?: string;
+  duration?: number;
+}
+
+/**
+ * Format query key for display
+ */
+function formatQueryKey(queryKey: unknown[] | undefined): string {
+  if (!queryKey || queryKey.length === 0) return "unknown";
+
+  return queryKey
+    .map((part) => {
+      if (typeof part === "string") return part;
+      if (typeof part === "number") return String(part);
+      if (typeof part === "object" && part !== null) {
+        const obj = part as Record<string, unknown>;
+        const firstValue = Object.values(obj)[0];
+        if (typeof firstValue === "string" || typeof firstValue === "number") {
+          return String(firstValue);
+        }
+        return JSON.stringify(part).slice(0, 20);
+      }
+      return String(part);
+    })
+    .join(" › ");
+}
+
+/**
+ * Get status for React Query event
+ */
+function getReactQueryStatus(event: ReactQueryEvent): EventStatus {
+  switch (event.type) {
+    case "query-fetch-start":
+    case "mutation-start":
+      return "pending";
+    case "query-fetch-success":
+    case "mutation-success":
+      return "success";
+    case "query-fetch-error":
+    case "mutation-error":
+      return "error";
+    case "query-invalidated":
+      return "neutral";
+    default:
+      return "neutral";
+  }
+}
+
+/**
+ * Get title for React Query event
+ */
+function getReactQueryTitle(event: ReactQueryEvent): string {
+  if (event.queryKey) {
+    return formatQueryKey(event.queryKey);
+  }
+  if (event.mutationKey) {
+    return formatQueryKey(event.mutationKey);
+  }
+  if (event.mutationId !== undefined) {
+    return `Mutation #${event.mutationId}`;
+  }
+  return event.type.replace(/-/g, " ");
+}
+
+/**
+ * Get subtitle for React Query event
+ */
+function getReactQuerySubtitle(event: ReactQueryEvent): string {
+  const parts: string[] = [];
+
+  switch (event.type) {
+    case "query-fetch-start":
+      parts.push("Fetching");
+      break;
+    case "query-fetch-success":
+      parts.push("Success");
+      break;
+    case "query-fetch-error":
+      parts.push("Error");
+      break;
+    case "query-invalidated":
+      parts.push("Invalidated");
+      break;
+    case "mutation-start":
+      parts.push("Mutating");
+      break;
+    case "mutation-success":
+      parts.push("Success");
+      break;
+    case "mutation-error":
+      parts.push("Error");
+      break;
+  }
+
+  if (event.duration !== undefined) {
+    parts.push(`${event.duration.toFixed(0)}ms`);
+  }
+
+  return parts.join(" · ");
+}
+
+/**
+ * Get correlation ID for React Query event
+ */
+function getReactQueryCorrelationId(event: ReactQueryEvent): string | undefined {
+  if (event.queryHash) {
+    return `rq-query-${event.queryHash}`;
+  }
+  if (event.mutationId !== undefined) {
+    return `rq-mutation-${event.mutationId}`;
+  }
+  return undefined;
+}
+
+/**
+ * Get sequence number within correlation group
+ */
+function getReactQuerySequence(event: ReactQueryEvent): number {
+  switch (event.type) {
+    case "query-fetch-start":
+    case "mutation-start":
+      return 1;
+    case "query-fetch-success":
+    case "query-fetch-error":
+    case "mutation-success":
+    case "mutation-error":
+      return 2;
+    case "query-invalidated":
+      return 3;
+    default:
+      return 1;
+  }
+}
+
+/**
+ * Determine if a React Query event is a mutation
+ */
+function isReactQueryMutation(event: ReactQueryEvent): boolean {
+  return event.type.startsWith("mutation-");
+}
+
+/**
+ * Transform ReactQueryEvent to UnifiedEvent
+ */
+export function transformReactQueryEvent(event: ReactQueryEvent): UnifiedEvent {
+  const isMutation = isReactQueryMutation(event);
+  return {
+    id: generateEventId(isMutation ? "react-query-mutation" : "react-query-query"),
+    source: isMutation ? "react-query-mutation" : "react-query-query",
+    timestamp: event.timestamp,
+    title: getReactQueryTitle(event),
+    subtitle: getReactQuerySubtitle(event),
+    status: getReactQueryStatus(event),
+    originalEvent: event,
+    correlationId: getReactQueryCorrelationId(event),
+    sequenceInGroup: getReactQuerySequence(event),
+  };
+}
+
+// ============================================================================
+// Route Event Types
+// ============================================================================
+
+/**
+ * Generic Route change event structure
+ */
+export interface RouteChangeEvent {
+  pathname: string;
+  params: Record<string, unknown>;
+  timestamp: number;
+  previousPathname?: string;
+  timeSincePrevious?: number;
+}
+
+/**
+ * Get status for route event
+ */
+function getRouteStatus(event: RouteChangeEvent): EventStatus {
+  if (event.pathname === "/") return "success";
+  if (Object.keys(event.params).length > 0) return "success";
+  return "neutral";
+}
+
+/**
+ * Get title for route event
+ */
+function getRouteTitle(event: RouteChangeEvent): string {
+  return event.pathname || "/";
+}
+
+/**
+ * Get subtitle for route event
+ */
+function getRouteSubtitle(event: RouteChangeEvent): string {
+  const parts: string[] = [];
+
+  const paramCount = Object.keys(event.params).length;
+  if (paramCount > 0) {
+    parts.push(`${paramCount} param${paramCount !== 1 ? "s" : ""}`);
+  }
+
+  if (event.timeSincePrevious !== undefined && event.timeSincePrevious > 0) {
+    if (event.timeSincePrevious < 1000) {
+      parts.push(`${event.timeSincePrevious}ms`);
+    } else {
+      parts.push(`${(event.timeSincePrevious / 1000).toFixed(1)}s`);
+    }
+  }
+
+  if (event.previousPathname && event.previousPathname !== event.pathname) {
+    parts.push(`from ${event.previousPathname}`);
+  }
+
+  return parts.join(" · ") || "navigation";
+}
+
+/**
+ * Transform RouteChangeEvent to UnifiedEvent
+ */
+export function transformRouteEvent(event: RouteChangeEvent): UnifiedEvent {
+  return {
+    id: generateEventId("route"),
+    source: "route",
+    timestamp: event.timestamp,
+    title: getRouteTitle(event),
+    subtitle: getRouteSubtitle(event),
+    status: getRouteStatus(event),
+    originalEvent: event,
+  };
+}