javascript

JavaScript

现代 JavaScript 和 Node 的通用规范。将其应用于你编写或修改的代码——除非有人要求，否则不要重构未改动的文件来符合这些规范。

规范

• 处处使用 ESM。 新建的包要设置 "type": "module"。在同一个包中混用 CJS 和 ESM 会产生双包隐患——同一个模块会有两个副本，状态彼此独立，故障表现还像是竞态条件。
• 根据意图选择组合方式。 在循环中依次 await 会串行处理彼此独立的工作；Promise.all 遇到一次拒绝就会丢弃整个批次；只有在可以接受部分成功时才使用 allSettled。选错了会导致延迟问题或错误被吞掉，这两种情况在代码审查中看起来都没问题。
• 每个 catch 都要处理错误或重新抛出。 只记录错误然后继续执行的 catch，会把故障转化为下游的状态错误，此时堆栈跟踪已无法指向根因。如果没有有用的处理方式，就不要捕获。
• 任何可取消的操作都使用 AbortController——fetch、计时器、流、监听器（{ signal }）。否则，已放弃的请求仍会让处理程序及其闭包保持存活。
• 绝不阻塞事件循环。 不要使用 readFileSync，也不要在请求路径中执行耗时的同步解析或加密：Node 用同一个线程处理其他所有请求。CPU 密集型工作应交给工作线程。
• 不要修改参数。 函数编辑输入会在调用方毫无赋值操作的情况下更改其对象。应返回新值，并使用现有的非变更数组方法，这些方法正是为此而存在的：toSorted、toReversed、toSpliced、with。arr.sort() 会原地排序调用方的数组，这是 JS 中最常见的意外变更之一。
• 内置模块使用 node: 前缀。 这样可以明确无歧义，并避免被同名用户态包遮蔽。
• 优先使用平台功能，而不是依赖包。 structuredClone、Intl、URL/URLSearchParams、crypto.randomUUID、Array.prototype.at/findLast、Object.groupBy 已涵盖了大多数原本需要安装工具库的用途。

发布包

exports 映射定义了公共接口——未列出的内容都无法访问，这正是它的意义：你可以重构内部实现，而不会破坏使用方。声明 sideEffects: false（或列出有副作用的文件），以便打包工具移除未使用的导出；如果不声明，摇树优化就必须假定导入模块会执行某些操作，因此会保留模块中的所有内容。

{
  "type": "module",
  "exports": {
    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
    "./package.json": "./package.json"
  },
  "sideEffects": false
}

两个最容易耗费时间的 ESM 特性：相对导入必须带文件扩展名（./utils.js，而不是 ./utils），并且没有 __dirname——使用 fileURLToPath(import.meta.url) 推导路径；如果确实需要加载仅支持 CJS 的包，则使用 createRequire(import.meta.url)。