/**
 * @utils —— 纯函数,零依赖(编码规范 §2 / §5.1:叶子包)。
 * 无业务语义;有业务语义的东西不属于这里。
 */

/** 穷尽性检查:switch 漏分支时编译期报错 */
export function assertNever(value: never, message = '未覆盖的分支'): never {
  throw new Error(`${message}: ${JSON.stringify(value)}`);
}

/** 类型守卫:滤掉 null / undefined */
export function isDefined<T>(value: T | null | undefined): value is T {
  return value !== null && value !== undefined;
}

/** 按键分组 */
export function groupBy<T, K extends string>(items: readonly T[], key: (item: T) => K): Record<K, T[]> {
  const out = {} as Record<K, T[]>;
  for (const item of items) {
    const k = key(item);
    (out[k] ??= []).push(item);
  }
  return out;
}

/** 稳定排序的键值对遍历(避免 Object.keys 顺序依赖) */
export function sortedEntries<V>(record: Readonly<Record<string, V>>): Array<[string, V]> {
  return Object.entries(record).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
}