Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

4.0 KB
Raw Blame
/* 后台任务:点一下起一趟,服务端在后台跑,页面按状态轮询,跟到终态报一次回执。
 *
 * 两条时序在这里定死,页面不各写一份:
 * - **首屏读到的旧终态不冒充新结果**。任务关掉页面照样在跑,状态里常年躺着上一趟的回执;
 *   只有本次启动过、或者本次见过它在跑,终态才交给 `onFinish`、落进 `outcome`。
 * - **启动成功时先把启动请求回的 `running` 快照换进缓存,再重读**。只重读的话,重读回来
 *   之前缓存里的上一趟终态会被当成这一趟的回执;这一趟在重读前就跑完时,结果也会被它顶掉。 */
import { useEffect, useRef, useState } from 'react';
import { useMutation, useQuery, type QueryKey } from '@tanstack/react-query';

import { queryClient } from './query';

export interface JobState { status?: string }

/** 在跑时两秒一次,和活动页同一个节律。 */
export const JOB_RUNNING_POLL_MS = 2000;

export interface BackgroundJobOptions<Job extends JobState, Args, Data> {
  queryKey: QueryKey;
  queryFn: (context: { signal: AbortSignal }) => Promise<Data>;
  start: (args: Args) => Promise<Job>;
  /** 缓存里存的是整张卡、任务只占一格时:任务在哪一格,新快照怎么换进去。 */
  jobOf?: (data: Data) => Job | undefined;
  withJob?: (data: Data | undefined, job: Job) => Data | undefined;
  /** 闲着时多久问一次。任务可能从别的页面或上一次会话里起来的页面才需要;默认不问。 */
  idlePollMs?: number;
  onStarted?: (started: Job) => void;
  onError?: (cause: unknown) => void;
  /** 本次跟完的那一趟到了终态,只调一次。 */
  onFinish?: (job: Job) => void;
}

const itself = <Job, Data>(data: Data) => data as unknown as Job;
const replaced = <Job, Data>(_data: Data | undefined, job: Job) => job as unknown as Data;

export function useBackgroundJob<Job extends JobState, Args = void, Data = Job>(
  options: BackgroundJobOptions<Job, Args, Data>,
) {
  const { queryKey, jobOf = itself<Job, Data>, withJob = replaced<Job, Data>, idlePollMs } = options;
  /** 本次是不是在跟一趟:启动过,或者本次见过它在跑。 */
  const [tracking, setTracking] = useState(false);
  /** 本次跟完的那一趟。首屏读到的旧终态不算,它不会走到这里。 */
  const [outcome, setOutcome] = useState<Job | null>(null);
  /* 回调由页面每次渲染新建,放进 ref 读最新的一份:进 effect 依赖的话,每画一遍都要重跑。 */
  const hooks = useRef(options);
  useEffect(() => { hooks.current = options });

  const query = useQuery({
    queryKey,
    queryFn: ({ signal }) => hooks.current.queryFn({ signal }),
    refetchInterval: (current) => {
      const data = current.state.data;
      return data !== undefined && jobOf(data)?.status === 'running' ? JOB_RUNNING_POLL_MS : (idlePollMs ?? false);
    },
  });
  const start = useMutation({
    mutationFn: (args: Args) => hooks.current.start(args),
    onSuccess: (started) => {
      setTracking(true);
      setOutcome(null);
      hooks.current.onStarted?.(started);
      queryClient.setQueryData<Data>(queryKey, (data) => withJob(data, started));
      /* `exact`:别的键可能以同一段开头,按前缀失效会把它们一起推倒重来。 */
      void queryClient.invalidateQueries({ queryKey, exact: true });
    },
    onError: (cause) => hooks.current.onError?.(cause),
  });

  const job = query.data === undefined ? undefined : jobOf(query.data);
  const running = job?.status === 'running';
  useEffect(() => {
    if (!job) return;
    if (job.status === 'running') {
      if (!tracking) setTracking(true);
      return;
    }
    if (!tracking) return;
    setTracking(false);
    setOutcome(job);
    hooks.current.onFinish?.(job);
  }, [job, tracking]);

  /** 收起本次的结果,比如用户关掉结果卡,或者结果已经登记完。 */
  const dismiss = () => setOutcome(null);

  return { query, job, running, outcome, start, dismiss };
}