为何@instantdb/admin包类型扩展引发无限循环，项目内却正常？

为什么index.d.ts会生成巨型类型扩展 #

这是TypeScript编译库类型定义时的特性导致的：

• 库源码里大概率用了递归的条件/映射类型（比如用来递归移除对象中的$前缀键、处理嵌套对象结构），这类类型在源码中是简洁的递归别名（比如type RemoveDollarKeys<T> = ... RemoveDollarKeys<...> ...）。
• 当TypeScript编译库生成.d.ts时，为了保证类型定义的自包含性（不依赖库内部的类型别名，让外部项目直接能解析），会自动展开所有递归类型，把递归逻辑转换成多层重复的嵌套类型结构。层级越深，生成的代码就越庞大，最终形成你看到的巨型类型扩展。
• 而直接在项目中使用库的index.ts源码时，TypeScript会保留原有的递归类型别名，编译器可以利用递归的惰性求值优化，不会一次性展开所有层级，因此IntelliSense能正常工作。

如何在TypeScript Playground复现该问题 #

按照以下步骤模拟库的编译流程，就能复现巨型类型的生成：

1. 在Playground中编写模拟原库核心类型逻辑的代码：

// 模拟库中的Exactly类型
type Exactly<T, U> = U extends T ? T extends U ? U : never : never;
// 模拟Query类型
type Query = Record<string, any>;

// 递归移除对象中的$前缀键，这是核心递归类型
type RemoveDollarKeys<T extends object> = {
  [K in keyof T as Exclude<K, "$">]: 
    T[K] extends object ? RemoveDollarKeys<T[K]> : T[K]
};

// 模拟init函数的类型
declare function init(): {
  query: <Q extends Query>(query: Exactly<Query, Q>) => Promise<RemoveDollarKeys<Q>>;
};

2. 开启类型声明生成：点击Playground右上角的「Options」，勾选「Declaration」选项。
3. 查看生成的.d.ts文件：此时你会看到RemoveDollarKeys递归类型被展开成多层嵌套的映射类型，结构和你在@instantdb/admin的index.d.ts中看到的巨型代码完全一致。

注：直接在Playground中悬停query可能不会立刻出现卡顿（Playground的tsserver资源限制和本地IDE不同），但生成的.d.ts结构已经复现了问题的核心。

内容的提问来源于stack exchange，提问作者Stepan Parunashvili