《互联网产品的客户端架构·内容、社交与实时互动》12.2 结果分页与筛选状态的保持

interface FirstPage {
  revision: number;
  items: number;
  nextCursor: string | null;
}

function applyFirst(state: SearchState, page: FirstPage): SearchState {
  if (page.revision !== state.revision) return state;
  if (page.items === 0) return { ...state, status: "empty", nextCursor: null };
  return { ...state, status: "ready", itemCount: page.items, nextCursor: page.nextCursor };
}

// file: src/search/search-state.ts
// tier: L1
// verify: node --test test/search/search-state.test.ts

export type SearchType = "all" | "post" | "user" | "topic";
export type SearchSort = "relevance" | "latest";
export type SearchTimeRange = "all" | "day" | "week" | "year";

export type SearchStatus = "idle" | "loading" | "loadingMore" | "ready" | "empty" | "error";

export interface SearchFilters {
  type?: SearchType;
  sort?: SearchSort;
  timeRange?: SearchTimeRange;
  tags?: string[];
}

export interface NormalizedFilters {
  type: SearchType;
  sort: SearchSort;
  timeRange: SearchTimeRange;
  tags: string[];
}

export interface SearchState {
  query: string;
  filters: NormalizedFilters;
  revision: number;
  status: SearchStatus;
  itemCount: number;
  nextCursor: string | null;
  error: string | null;
}

export type SearchAction =
  | { type: "query"; value: string }
  | { type: "filter"; patch: SearchFilters }
  | { type: "submit" }
  | { type: "moreStart" }
  | { type: "first"; revision: number; items: number; nextCursor: string | null }
  | { type: "more"; revision: number; items: number; nextCursor: string | null }
  | { type: "fail"; revision: number; message: string }
  | { type: "clear" };

export const DEFAULT_FILTERS: NormalizedFilters = {
  type: "all",
  sort: "relevance",
  timeRange: "all",
  tags: [],
};

const TYPES: SearchType[] = ["all", "post", "user", "topic"];
const SORTS: SearchSort[] = ["relevance", "latest"];
const TIMES: SearchTimeRange[] = ["all", "day", "week", "year"];

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

export function normalizeTags(tags: string[]): string[] {
  return [...new Set(tags.map((tag) => tag.trim()).filter((tag) => tag !== ""))].sort();
}

export function normalizeFilters(
  patch: SearchFilters = {},
  base: NormalizedFilters = DEFAULT_FILTERS,
): NormalizedFilters {
  return {
    type: patch.type ?? base.type,
    sort: patch.sort ?? base.sort,
    timeRange: patch.timeRange ?? base.timeRange,
    tags: normalizeTags(patch.tags ?? base.tags),
  };
}

export function sameFilters(a: NormalizedFilters, b: NormalizedFilters): boolean {
  return (
    a.type === b.type &&
    a.sort === b.sort &&
    a.timeRange === b.timeRange &&
    a.tags.length === b.tags.length &&
    a.tags.every((tag, index) => tag === b.tags[index])
  );
}

export function createSearchState(query = "", filters: SearchFilters = {}): SearchState {
  return {
    query: normalizeQuery(query),
    filters: normalizeFilters(filters),
    revision: 1,
    status: "idle",
    itemCount: 0,
    nextCursor: null,
    error: null,
  };
}

export function reduce(state: SearchState, action: SearchAction): SearchState {
  switch (action.type) {
    case "query": {
      const query = normalizeQuery(action.value);
      if (query === state.query) return state;
      return { ...state, query, revision: state.revision + 1, status: "idle", itemCount: 0, nextCursor: null, error: null };
    }
    case "filter": {
      const filters = normalizeFilters(action.patch, state.filters);
      if (sameFilters(filters, state.filters)) return state;
      return {
        ...state,
        filters,
        revision: state.revision + 1,
        status: "idle",
        itemCount: 0,
        nextCursor: null,
        error: null,
      };
    }
    case "submit":
      return {
        ...state,
        revision: state.revision + 1,
        status: "loading",
        itemCount: 0,
        nextCursor: null,
        error: null,
      };
    case "moreStart":
      if (state.status !== "ready" || state.nextCursor === null) return state;
      return { ...state, status: "loadingMore", error: null };
    case "first": {
      if (action.revision !== state.revision) return state;
      if (action.items === 0) {
        return { ...state, status: "empty", itemCount: 0, nextCursor: null, error: null };
      }
      return { ...state, status: "ready", itemCount: action.items, nextCursor: action.nextCursor, error: null };
    }
    case "more": {
      if (action.revision !== state.revision) return state;
      if (state.status !== "loadingMore") return state;
      const itemCount = state.itemCount + action.items;
      // 服务端原地返回同一个游标说明分页没有推进，再请求只会死循环。
      const repeated = state.nextCursor !== null && action.nextCursor === state.nextCursor;
      const nextCursor = repeated ? null : action.nextCursor;
      return { ...state, status: itemCount === 0 ? "empty" : "ready", itemCount, nextCursor, error: null };
    }
    case "fail": {
      if (action.revision !== state.revision) return state;
      // 已有内容时加载更多失败不应清空列表，只把错误挂出来等重试。
      return { ...state, status: state.itemCount > 0 ? "ready" : "error", error: action.message };
    }
    case "clear":
      return createSearchState();
  }
}

export function hasMore(state: SearchState): boolean {
  return state.status === "ready" && state.nextCursor !== null;
}

export function isExhausted(state: SearchState): boolean {
  return state.status === "ready" && state.itemCount > 0 && state.nextCursor === null;
}

export function isEmpty(state: SearchState): boolean {
  return state.status === "empty";
}

export function retryAction(state: SearchState): SearchAction {
  if (state.itemCount > 0 && state.nextCursor !== null) return { type: "moreStart" };
  return { type: "submit" };
}

export function encodeSearch(state: Pick<SearchState, "query" | "filters">): string {
  const params = new URLSearchParams();
  if (state.query !== "") params.set("q", state.query);
  if (state.filters.type !== "all") params.set("type", state.filters.type);
  if (state.filters.sort !== "relevance") params.set("sort", state.filters.sort);
  if (state.filters.timeRange !== "all") params.set("time", state.filters.timeRange);
  if (state.filters.tags.length > 0) params.set("tags", [...state.filters.tags].sort().join(","));
  return params.toString();
}

export function decodeSearch(search: string): Pick<SearchState, "query" | "filters"> {
  const params = new URLSearchParams(search.startsWith("?") ? search.slice(1) : search);
  const tags = (params.get("tags") ?? "")
    .split(",")
    .map((tag) => tag.trim())
    .filter((tag) => tag !== "");
  return {
    query: normalizeQuery(params.get("q") ?? ""),
    filters: normalizeFilters({
      type: pick(TYPES, params.get("type"), "all"),
      sort: pick(SORTS, params.get("sort"), "relevance"),
      timeRange: pick(TIMES, params.get("time"), "all"),
      tags,
    }),
  };
}

export function restoreSearch(search: string): SearchState {
  const { query, filters } = decodeSearch(search);
  return createSearchState(query, filters);
}

function pick<T extends string>(allowed: T[], value: string | null, fallback: T): T {
  return allowed.includes(value as T) ? (value as T) : fallback;
}

$ node --test --test-concurrency=1 test/search/search-state.test.ts
✔ 查询词变化重置游标与已加载条目 (0.677ms)
✔ 筛选变化重置状态，相同筛选不产生新版本 (0.856708ms)
✔ 旧版本的首页与翻页响应都被丢弃 (0.090709ms)
✔ 空结果与「没有更多」是两种状态 (0.167792ms)
✔ 加载更多累加条目，重复游标判定为耗尽 (0.078917ms)
✔ URL 只编码查询条件，不包含游标或位置 (0.161ms)
✔ URL 解码校验非法值，标签去重排序并可往返 (0.229375ms)
✔ 失败保留已有内容并给出正确的重试动作 (0.097375ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 150.054042