类型化错误处理

// 盲区一：签名看不出来会抛
function readConfig(path: string): Config {
  const raw = fs.readFileSync(path, 'utf-8'); // 可能抛，签名里没有
  return JSON.parse(raw);                     // 也可能抛
}
const conf = readConfig('./a.json'); // 调用方没有任何"必须 try"的提示

// 盲区二：catch 的 unknown 没有形状
try {
  readConfig('./a.json');
} catch (e) {
  console.log(e.code); // 报错：e 是 unknown，摸不到任何属性
}

type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };

function readConfigR(path: string): Result<Config, ConfigError> { /* ... */ }

const r = readConfigR('./a.json');
if (r.ok) {
  use(r.value);      // 分支内 r.value 合法
} else {
  report(r.error);   // 分支内 r.error 合法
}
// 想直接用 r.value？编译器：你可能拿到的是失败分支。

type Ok<T> = { ok: true; value: T };
type Err<E> = { ok: false; error: E };
type Result<T, E> = Ok<T> | Err<E>;

// 两个构造器：让调用点不用手写 ok: true
const ok = <T>(value: T): Ok<T> => ({ ok: true, value });
const err = <E>(error: E): Err<E> => ({ ok: false, error });

// 场景一：解析器——"字符串进，结构出，解析不了就报错"
function parsePage(raw: string): Result<number, string> {
  const n = Number(raw);
  return Number.isInteger(n) && n > 0 ? ok(n) : err(`非法页码: ${raw}`);
}

// 场景二：查表——找不到是常态而不是异常
function findDoc(id: string): Result<Doc, 'not_found'> {
  const hit = store.get(id);
  return hit ? ok(hit) : err('not_found');
}

// 场景三：链式——把"上一步失败就停"写成类型驱动的管道
function andThen<T, U, E>(r: Result<T, E>, next: (v: T) => Result<U, E>): Result<U, E> {
  return r.ok ? next(r.value) : r;
}

const page = andThen(parsePage(raw), (n) => fetchPageR(n));
// parsePage 失败时 fetchPageR 根本不会被调用，类型层层传递

// 错误码表：整个模块的错误"词表"
type FetchErr =
  | { kind: 'network'; message: string }
  | { kind: 'status'; code: number }
  | { kind: 'abort' };

async function fetchJson<T>(url: string, signal?: AbortSignal): Promise<Result<T, FetchErr>> {
  try {
    const res = await fetch(url, { signal });
    if (!res.ok) return err({ kind: 'status', code: res.status });
    return ok((await res.json()) as T);
  } catch (e) {
    // ---- unknown 收窄三步 ----
    if (e instanceof DOMException && e.name === 'AbortError') {
      return err({ kind: 'abort' });                       // 已知：主动取消
    }
    if (e instanceof TypeError) {
      return err({ kind: 'network', message: e.message }); // 已知：fetch 网络失败
    }
    return err({ kind: 'network', message: String(e) });   // 兜底：转字符串封箱
  }
}

type ReadResult =
  | { state: 'loaded'; text: string; bytes: number }
  | { state: 'empty' }                       // 文件存在但为空：不是错误
  | { state: 'failed'; reason: 'missing' | 'permission' };

function readNote(path: string): ReadResult {
  try {
    const text = readFileSyncText(path);
    return text.length === 0 ? { state: 'empty' } : { state: 'loaded', text, bytes: text.length };
  } catch (e) {
    const code = (e as NodeJS.ErrnoException).code; // Node 错误码在 error 对象上
    return {
      state: 'failed',
      reason: code === 'ENOENT' ? 'missing' : 'permission',
    };
  }
}

function render(r: ReadResult): string {
  switch (r.state) {
    case 'loaded':  return r.text.slice(0, 200);
    case 'empty':   return '（空笔记）';
    case 'failed':  return r.reason === 'missing' ? '笔记不存在' : '无法读取';
  }
}

// 服务端错误码表（来自接口文档，用 satisfies 锁住不漂移）
const PAGE_ERROR_CODES = {
  INVALID_PAGE: 40001,
  PAGE_GONE: 40010,
  RATE_LIMITED: 40290,
} as const;

type PageErrCode = keyof typeof PAGE_ERROR_CODES; // 'INVALID_PAGE' | 'PAGE_GONE' | 'RATE_LIMITED'

type PageResult<T> =
  | { ok: true; items: T; nextCursor: string | null }
  | { ok: false; code: PageErrCode; retryAfter?: number };

async function fetchPage<T>(cursor: string): Promise<PageResult<T>> {
  const res = await fetch(`/api/list?cursor=${encodeURIComponent(cursor)}`);
  const body = await res.json();
  if (body.errorCode === PAGE_ERROR_CODES.PAGE_GONE) return { ok: false, code: 'PAGE_GONE' };
  if (body.errorCode === PAGE_ERROR_CODES.RATE_LIMITED) {
    return { ok: false, code: 'RATE_LIMITED', retryAfter: body.retryAfter };
  }
  if (body.errorCode === PAGE_ERROR_CODES.INVALID_PAGE) return { ok: false, code: 'INVALID_PAGE' };
  return { ok: true, items: body.items, nextCursor: body.nextCursor };
}

async function loadMore(cursor: string): Promise<void> {
  const r = await fetchPage<NoteMeta>(cursor);
  if (!r.ok) {
    switch (r.code) {
      case 'PAGE_GONE':    return resetToFirstPage();
      case 'RATE_LIMITED': return setTimeout(loadMore, (r.retryAfter ?? 5) * 1000, cursor);
      case 'INVALID_PAGE': return console.error('cursor 已损坏，清空本地状态');
      default: {
        const never: never = r.code; // 新增错误码时这里编译报错
        return never;
      }
    }
  }
  appendItems(r.items);
}

type ImportRow<T> = { line: number; input: T };

type RowOutcome<T> =
  | { line: number; status: 'imported'; value: T }
  | { line: number; status: 'rejected'; error: string };

function importOne(raw: string): Result<NoteMeta, string> {
  // ...逐行解析 + 校验，失败返回 err(原因)
  return raw.trim() === '' ? err('空行') : ok(JSON.parse(raw) as NoteMeta);
}

function importBatch(rows: ImportRow<string>[]): { summary: string; outcomes: RowOutcome<NoteMeta>[] } {
  const outcomes = rows.map(({ line, input }) => {
    const r = importOne(input);
    return r.ok
      ? { line, status: 'imported', value: r.value } as const
      : { line, status: 'rejected', error: r.error } as const;
  });

  const rejected = outcomes.filter((o) => o.status === 'rejected');
  const summary = `共 ${rows.length} 行，成功 ${outcomes.length - rejected.length} 行，失败 ${rejected.length} 行`;
  return { summary, outcomes };
}