Autocomplete System Design

flowchart TD
    A["User Input"] --> B["Debounce (等待 300ms)"]
    B --> C{"Check Cache"}
    C -->|"Hit"| D["Return Cached"]
    C -->|"Miss"| E["API Request"]
    E --> F["Update Cache"]
    F --> D
    D --> G["Update State"]
    G --> H["Render Results"]

interface AutocompleteState<T> {
  // 輸入相關
  query: string;
 
  // 結果相關
  results: T[];
  isLoading: boolean;
  error: Error | null;
 
  // UI 相關
  isOpen: boolean;
  highlightedIndex: number;
}
 
// 初始狀態
const initialState: AutocompleteState<unknown> = {
  query: "",
  results: [],
  isLoading: false,
  error: null,
  isOpen: false,
  highlightedIndex: -1,
};

interface CacheEntry<T> {
  data: T[];
  timestamp: number;
  expiresAt: number;
}
 
interface CacheConfig {
  maxSize: number; // 最大快取數量，建議 50-100
  ttl: number; // Time to live (ms)，建議 5 分鐘
  strategy: "lru" | "fifo"; // 淘汰策略，建議 LRU
}

interface AutocompleteProps<T> {
  // === 核心功能 ===
  fetchSuggestions: (query: string) => Promise<T[]>;
  onSelect?: (item: T) => void;
 
  // === 受控模式（可選）===
  value?: string;
  onChange?: (value: string) => void;
 
  // === 行為配置 ===
  debounceMs?: number; // default: 300
  minQueryLength?: number; // default: 1
  maxResults?: number; // default: 10
 
  // === 自訂渲染（Render Props Pattern）===
  renderItem?: (item: T, highlighted: boolean) => ReactNode;
  renderEmpty?: () => ReactNode;
  renderLoading?: () => ReactNode;
 
  // === 無障礙 ===
  id?: string;
  ariaLabel?: string;
  placeholder?: string;
}

<Autocomplete
  fetchSuggestions={async (query) => {
    const res = await fetch(`/api/search?q=${query}`);
    return res.json();
  }}
  onSelect={(item) => console.log("Selected:", item)}
  placeholder="Search..."
/>

interface User {
  id: string;
  name: string;
  avatar: string;
  email: string;
}
 
<Autocomplete<User>
  // 核心
  fetchSuggestions={searchUsers}
  onSelect={(user) => router.push(`/users/${user.id}`)}
  // 行為
  debounceMs={300}
  minQueryLength={2}
  maxResults={8}
  // 自訂渲染
  renderItem={(user, highlighted) => (
    <div className={cn("flex items-center gap-3 p-2", highlighted && "bg-blue-50")}>
      <img src={user.avatar} className="w-8 h-8 rounded-full" />
      <div>
        <p className="font-medium">{user.name}</p>
        <p className="text-sm text-gray-500">{user.email}</p>
      </div>
    </div>
  )}
  renderEmpty={() => <p className="p-4 text-center text-gray-500">No users found</p>}
  // 無障礙
  id="user-search"
  ariaLabel="Search for users"
  placeholder="Type a name..."
/>;

// GET /api/search?q={query}&limit={limit}&offset={offset}
 
// Request Query Params
interface SearchParams {
  q: string; // 搜尋關鍵字
  limit?: number; // 每頁數量，default: 10
  offset?: number; // 分頁偏移，default: 0
}
 
// Response
interface SearchResponse<T> {
  results: T[];
  total: number;
  hasMore: boolean;
}
 
// Error Response
interface ErrorResponse {
  error: string;
  code: "INVALID_QUERY" | "RATE_LIMITED" | "SERVER_ERROR";
}

// 簡化版 - 實務上可用 lodash.debounce 或 use-debounce
const debouncedSearch = useDebouncedCallback((query: string) => {
  fetchSuggestions(query);
}, 300);

// 方法一：Request ID - 只用最新請求的結果
const requestId = useRef(0);
 
async function search(query: string) {
  const currentId = ++requestId.current;
  const result = await fetchSuggestions(query);
 
  // 丟棄過期的結果
  if (currentId !== requestId.current) return;
 
  setResults(result);
}

// 方法二：AbortController - 取消前一個請求
const controllerRef = useRef<AbortController>();
 
async function search(query: string) {
  controllerRef.current?.abort(); // 取消前一個
  controllerRef.current = new AbortController();
 
  const result = await fetch(`/api/search?q=${query}`, {
    signal: controllerRef.current.signal,
  });
}

class LRUCache<T> {
  private cache = new Map<string, { data: T[]; expiresAt: number }>();
 
  get(key: string): T[] | null {
    const entry = this.cache.get(key);
    if (!entry || Date.now() > entry.expiresAt) return null;
 
    // LRU 關鍵：移到最後（最新）
    this.cache.delete(key);
    this.cache.set(key, entry);
    return entry.data;
  }
 
  set(key: string, data: T[]): void {
    // 超過容量，刪除第一個（最舊）
    if (this.cache.size >= 100) {
      const oldest = this.cache.keys().next().value;
      this.cache.delete(oldest);
    }
    this.cache.set(key, { data, expiresAt: Date.now() + 5 * 60 * 1000 });
  }
}

function handleKeyDown(e: KeyboardEvent) {
  switch (e.key) {
    case "ArrowDown":
      e.preventDefault();
      setHighlightedIndex((prev) => Math.min(prev + 1, results.length - 1));
      break;
    case "ArrowUp":
      e.preventDefault();
      setHighlightedIndex((prev) => Math.max(prev - 1, 0));
      break;
    case "Enter":
      if (highlightedIndex >= 0) onSelect(results[highlightedIndex]);
      break;
    case "Escape":
      setIsOpen(false);
      break;
  }
}

<div role="combobox" aria-expanded={isOpen} aria-haspopup="listbox">
  <input
    aria-autocomplete="list"
    aria-activedescendant={highlightedIndex >= 0 ? `option-${highlightedIndex}` : undefined}
  />
  <ul role="listbox">
    {results.map((item, i) => (
      <li key={i} id={`option-${i}`} role="option" aria-selected={i === highlightedIndex}>
        {item.name}
      </li>
    ))}
  </ul>
</div>

function highlightMatch(text: string, query: string) {
  const escaped = query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
  const parts = text.split(new RegExp(`(${escaped})`, "gi"));
  return parts.map((part, i) =>
    part.toLowerCase() === query.toLowerCase() ? <mark key={i}>{part}</mark> : part,
  );
}
// highlightMatch("TypeScript", "type") → <mark>Type</mark>Script