typescript-conventions

用途：为 TypeScript（含内嵌 TypeScript 的 .ts、.tsx 文件）的编写、评审和重构提供编码约定。使用时先遵循当前文件所在仓库的文档、AGENTS.md、lint 规则和配置，并可结合框架、测试或库相关技能。\n\n主要约定：运行时校验 schema 使用 Valibot，并遵循项目的 schema 组织方式、尽量复用已有契约。避免 return undefined，函数无值退出时使用裸 return。非平凡的中间计算在嵌入参数、属性值、数组元素、条件、循环输入、展开来源或返回值前，应赋给有意义的 const 或 let 命名；但属性访问、可选链、??、一元判断、简单比较和一步算术等一目了然的简单表达式保持内联。有依赖的语句按执行顺序排列：先解析输入，再转换，再消费结果。在声明式库 API（嵌入式 DSL）中若嵌套或链式调用表达的是 schema、查询或规则集等声明，可保留其结构；但普通数据准备应抽取，例如先命名 parseId(rawId) 的结果再用于 eq(users.id, id)。需保持行为和算法复杂度，不得仅为格式新增中间集合或额外遍历。\n\n避免无意义的直通包装函数：仅调用另一函数并直接返回结果的包装应内联或在用途处改名，除非包装命名了真实概念或承担校验、分支、重试、映射、埋点、错误处理等行为。包装类型化 API 时优先复用源类型和推断，仅当包装拥有更窄契约或类型检查证明推断不足时才加本地命名类型；若改变返回或错误形态、生命周期、校验、映射或副作用，应命名所拥有的契约并测试。\n\n对象或数组展开需有具体目的，例如不可变地修改部分字段、合并集合或创建必需的所有权边界；若原值不会被修改且共享安全，应直接复用而非浅拷贝；构造视图模型或 API 载荷时应显式列出属性，避免宽泛展开隐藏契约。编写与评审时应能说明每个展开的目的，必要且不明显时加简短注释。\n\n接口结构保持扁平：接口声明与命名对象类型别名只保留一层命名属性；对象形状应抽为单独命名接口再引用，适用于直接属性、对象数组及可空或联合形式。该规则仅覆盖类型声明，不适用于运行时对象字面量、校验 schema、框架配置或库 DSL 值。共享工具（导出的 helper、composable、service 等）仅在附近层次易混淆时加简短角色级注释，说明其拥有的契约；避免逐行注释，应改进命名或拆分函数。\n\n限制：本次资料未提供价格、平台、安装方式等更多信息。