《互联网产品的客户端架构·内容、社交与实时互动》12.1 输入联想：防抖、竞态与缓存

function schedule(text: string): void {
  if (timer !== null) clearTimeout(timer);
  timer = setTimeout(() => {
    timer = null;
    void fetchSuggestions(text);
  }, delayMs);
}

// file: src/search/suggest.ts
// tier: L2
// verify: node --test --test-concurrency=1 test/search/suggest.test.ts

export interface SuggestItem {
  text: string;
  kind: "history" | "query" | "user" | "topic";
  score: number;
}

export interface SuggestRequest {
  query: string;
  seq: number;
  signal: AbortSignal;
}

export type SuggestFetcher = (request: SuggestRequest) => Promise<SuggestItem[]>;

export interface Scheduler {
  schedule(callback: () => void, delayMs: number): number;
  cancel(handle: number): void;
}

export type SuggestStatus = "idle" | "debouncing" | "loading" | "ready" | "empty" | "error";

export interface SuggestSnapshot {
  status: SuggestStatus;
  query: string;
  items: SuggestItem[];
  fromCache: boolean;
  staleDropped: number;
  aborted: number;
}

export interface SuggestOptions {
  delayMs?: number;
  limit?: number;
  cacheLimit?: number;
}

export function suggestCacheKey(query: string): string {
  return query.trim().replace(/\s+/g, " ").toLowerCase();
}

export class SuggestController {
  #fetcher: SuggestFetcher;
  #scheduler: Scheduler;
  #delayMs: number;
  #limit: number;
  #cacheLimit: number;

  #draft = "";
  #query = "";
  #composing = false;
  #timer: number | null = null;
  #seq = 0;
  #controller: AbortController | null = null;
  #inflight: Promise<void> | null = null;

  #status: SuggestStatus = "idle";
  #items: SuggestItem[] = [];
  #fromCache = false;
  #staleDropped = 0;
  #aborted = 0;
  #cache = new Map<string, SuggestItem[]>();

  constructor(fetcher: SuggestFetcher, scheduler: Scheduler, options: SuggestOptions = {}) {
    const delayMs = options.delayMs ?? 250;
    const limit = options.limit ?? 8;
    const cacheLimit = options.cacheLimit ?? 32;
    if (!Number.isFinite(delayMs) || delayMs < 0) throw new Error("delayMs 必须是非负数");
    if (!Number.isInteger(limit) || limit < 1) throw new Error("limit 必须是正整数");
    if (!Number.isInteger(cacheLimit) || cacheLimit < 0) throw new Error("cacheLimit 必须是非负整数");
    this.#fetcher = fetcher;
    this.#scheduler = scheduler;
    this.#delayMs = delayMs;
    this.#limit = limit;
    this.#cacheLimit = cacheLimit;
  }

  get snapshot(): SuggestSnapshot {
    return {
      status: this.#status,
      query: this.#query,
      items: [...this.#items],
      fromCache: this.#fromCache,
      staleDropped: this.#staleDropped,
      aborted: this.#aborted,
    };
  }

  get composing(): boolean {
    return this.#composing;
  }

  setComposing(composing: boolean): void {
    if (composing === this.#composing) return;
    this.#composing = composing;
    if (composing) {
      this.#cancelTimer();
      return;
    }
    this.#schedule(this.#draft);
  }

  type(text: string): void {
    this.#draft = text;
    if (this.#composing) {
      this.#cancelTimer();
      return;
    }
    this.#schedule(text);
  }

  clear(): void {
    this.#draft = "";
    this.#cancelTimer();
    this.#invalidate();
    this.#query = "";
    this.#items = [];
    this.#fromCache = false;
    this.#status = "idle";
  }

  async idle(): Promise<void> {
    while (this.#inflight) {
      await this.#inflight;
    }
  }

  #schedule(text: string): void {
    this.#cancelTimer();
    if (text.trim() === "") {
      this.#invalidate();
      this.#query = "";
      this.#items = [];
      this.#fromCache = false;
      this.#status = "idle";
      return;
    }
    if (text === this.#query && (this.#status === "ready" || this.#status === "empty")) return;
    this.#invalidate();
    const key = suggestCacheKey(text);
    const cached = this.#cache.get(key);
    if (cached) {
      this.#touchCache(key);
      this.#query = text;
      this.#items = cached.slice(0, this.#limit);
      this.#fromCache = true;
      this.#status = this.#items.length > 0 ? "ready" : "empty";
      return;
    }
    this.#query = text;
    this.#items = [];
    this.#fromCache = false;
    this.#status = "debouncing";
    this.#timer = this.#scheduler.schedule(() => {
      this.#timer = null;
      void this.#fire(text);
    }, this.#delayMs);
  }

  #fire(query: string): void {
    const controller = new AbortController();
    this.#controller = controller;
    this.#items = [];
    this.#fromCache = false;
    this.#status = "loading";
    const seq = this.#seq;
    this.#inflight = this.#run(seq, query, controller);
  }

  async #run(seq: number, query: string, controller: AbortController): Promise<void> {
    try {
      const items = await this.#fetcher({ query, seq, signal: controller.signal });
      if (seq !== this.#seq) {
        this.#staleDropped += 1;
        return;
      }
      this.#store(query, items);
      this.#items = items.slice(0, this.#limit);
      this.#fromCache = false;
      this.#status = this.#items.length > 0 ? "ready" : "empty";
    } catch {
      if (controller.signal.aborted) return;
      if (seq !== this.#seq) {
        this.#staleDropped += 1;
        return;
      }
      this.#items = [];
      this.#fromCache = false;
      this.#status = "error";
    } finally {
      if (this.#controller === controller) {
        this.#controller = null;
        this.#inflight = null;
      }
    }
  }

  #invalidate(): void {
    this.#seq += 1;
    if (this.#controller) {
      this.#aborted += 1;
      this.#controller.abort();
      this.#controller = null;
    }
  }

  #store(query: string, items: SuggestItem[]): void {
    if (this.#cacheLimit === 0) return;
    const key = suggestCacheKey(query);
    this.#cache.delete(key);
    this.#cache.set(key, [...items]);
    while (this.#cache.size > this.#cacheLimit) {
      const oldest = this.#cache.keys().next().value as string | undefined;
      if (oldest === undefined) break;
      this.#cache.delete(oldest);
    }
  }

  #touchCache(key: string): void {
    const items = this.#cache.get(key);
    if (!items) return;
    this.#cache.delete(key);
    this.#cache.set(key, items);
  }

  #cancelTimer(): void {
    if (this.#timer === null) return;
    this.#scheduler.cancel(this.#timer);
    this.#timer = null;
  }
}

$ node --test --test-concurrency=1 test/search/suggest.test.ts
✔ 防抖把连续输入合并成一次请求 (1.222042ms)
✔ 输入法组合期间不触发，组合结束后才排期 (0.170084ms)
✔ 新输入立即取消在途请求 (0.115209ms)
✔ 慢请求后到不能覆盖新结果 (0.540792ms)
✔ 缓存命中不再发请求，且 key 是完整查询词 (0.193083ms)
✔ 空输入清空结果、取消排期并中止在途请求 (0.167833ms)
✔ 请求失败进入 error，同一查询不会误用失败的缓存 (0.153292ms)
✔ 结果按 limit 截断但仍缓存完整列表 (0.120792ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 178.813167