moai-lang-javascript

快速参考（30 秒）

JavaScript ES2024+ 开发专家——使用 Node.js 22 LTS、多种运行时和现代工具开发现代 JavaScript。

自动触发：扩展名为 .js、.mjs 或 .cjs 的文件、package.json、Node.js 项目、JavaScript 相关讨论

核心技术栈：

• ES2024+：Set 方法、Promise.withResolvers、不可变数组、导入属性
• Node.js 22 LTS：原生 TypeScript、内置 WebSocket、稳定的监视模式
• 运行时：Node.js 20 和 22 LTS、Deno 2.x、Bun 1.x
• 测试：Vitest、Jest、Node.js 测试运行器
• 代码检查：ESLint 9 扁平配置、Biome
• 打包工具：Vite、esbuild、Rollup
• 框架：Express、Fastify、Hono、Koa

快速命令：

使用 npm create vite，配合 latest 标签、项目名称和 vanilla 模板创建 Vite 项目。使用 npm init 初始化，并通过带有 D 标志的 npm install 安装 vitest、eslint 和 eslint/js，配置现代工具链。使用带有 watch 标志的 Node.js 启动项目。在 Node.js 22+ 中使用带有 experimental-strip-types 标志的 node 直接运行 TypeScript。

---

实施指南（5 分钟）

ES2024 主要功能

Set 操作：

创建 setA，包含值 1、2、3、4；再创建 setB，包含值 3、4、5、6。调用 setA.intersection，并传入 setB，得到包含 3 和 4 的 Set。调用 setA.union，并传入 setB，得到包含 1 到 6 的 Set。调用 setA.difference，并传入 setB，得到包含 1 和 2 的 Set。调用 setA.symmetricDifference，并传入 setB，得到包含 1、2、5 和 6 的 Set。使用 isSubsetOf、isSupersetOf 和 isDisjointFrom 方法比较 Set。

Promise.withResolvers：

创建 createDeferred 函数，从 Promise.withResolvers 调用的结果中解构出 promise、resolve 和 reject。返回包含这三个属性的对象。创建一个 deferred 实例，设置一个定时器，在 1000 毫秒后使用 done 调用 resolve，并等待 promise 获取结果。

不可变数组方法：

创建一个原始数组，包含值 3、1、4、1、5。调用 toSorted，获取排序后的新数组，不修改原数组。调用 toReversed，获取反转后的新数组。调用 toSpliced，使用索引 1、删除数量 2，并插入值 9。调用 with 方法，在索引 2 处使用值 99，获取替换了元素的新数组。原数组保持不变。

Object.groupBy 和 Map.groupBy：

创建 items 数组，其中的对象包含 type 和 name 属性。调用 Object.groupBy，传入 items 和一个返回 item.type 的函数，得到一个按类型分组、值为数组的对象。使用相同参数调用 Map.groupBy，得到一个以类型为键、数组为值的 Map。

ES2025 功能

JSON 模块的导入属性：

从 config.json 导入 config，并将 type 属性设为 json。从 styles.css 导入 styles，并将 type 属性设为 css。访问 config.apiUrl 属性。

RegExp.escape：

创建一个包含括号等特殊字符的 userInput 字符串。调用 RegExp.escape，并传入 userInput，获取转义后的模式字符串。使用安全模式创建新的 RegExp。

Node.js 22 LTS 功能

内置 WebSocket 客户端：

使用 wss URL 创建新的 WebSocket。为 open 事件添加事件监听器，发送 JSON 序列化后的消息。为 message 事件添加事件监听器，将 event.data 解析为 JSON，并记录接收到的数据。

原生 TypeScript 支持（实验性）：

在 Node.js 22.6+ 中，使用带有 experimental-strip-types 标志的 node 直接运行 .ts 文件。在 Node.js 22.18+ 中，默认启用类型剥离，因此可以直接运行文件。

稳定的监视模式：

使用带有 watch 标志的 node，在文件更改时自动重启。多次使用 watch-path 标志来监视特定目录，例如 src 和 config。

权限模型：

使用带有 permission 标志的 node，并将 allow-fs-read 设为特定路径，以限制文件系统访问。使用 allow-net 标志和域名来限制网络访问。

后端框架

Express 传统模式：

导入 express。调用 express 函数创建 app。使用 express.json 中间件。创建一个位于 api/users 的 get 端点，等待数据库查询并以 json 响应。创建一个 post 端点，用于创建用户，并以状态码 201 和 json 响应。调用 listen 监听端口 3000，并在回调中记录服务器正在运行。

Fastify 高性能模式：

导入 Fastify。创建 fastify 实例，并将 logger 设为 true。定义 userSchema，其中 body 包含 type object、包含 name 和 email 的 required 数组，以及带有验证约束的 properties。创建一个带有 schema 选项的 post 端点，并使用 async 处理函数创建用户，然后以 code 201 返回。调用 listen，端口设为 3000。

Hono 边缘优先模式：

导入 Hono 和中间件函数。创建 app 实例。为所有路由使用 logger 中间件。为 api 路由使用 cors 中间件。创建一个位于 api/users 的 get 端点，等待数据库查询并返回 c.json。创建一个 post 端点，使用 validator 中间件检查必填字段，然后创建用户并以状态码 201 返回 c.json。将 app 作为默认值导出。

使用 Vitest 进行测试

配置：

创建 vitest.config.js，并使用 defineConfig。设置 test 对象，其中 globals 为 true，environment 为 node，coverage 使用 provider v8 和 text、json、html 报告器。

测试示例：

在测试文件中，从 vitest 导入 describe、it、expect、vi 和 beforeEach。导入要测试的函数。创建一个针对 User Service 的 describe 块。在 beforeEach 中调用 vi.clearAllMocks。创建一个名为 should create a user 的 it 块，等待 createUser，并断言结果与包含 name 和 email 的对象匹配，且 id 已定义。创建一个名为 should throw on invalid email 的 it 块，断言 createUser 因 Invalid email 错误而被拒绝。

ESLint 9 扁平配置

创建 eslint.config.js。从 eslint/js 导入 js，并导入 globals。导出一个数组，先放入 js.configs.recommended，然后放入一个包含 languageOptions 的对象，其中 ecmaVersion 为 2025，sourceType 为 module，globals 合并 globals.node 和 globals.es2025。设置规则：no-unused-vars 设为 error 并设置 args ignore pattern，no-console 设为 warn 并设置允许的方法，prefer-const 设为 error，no-var 设为 error。

Biome 一体化方案

创建 biome.json，并添加 schema URL。启用 organizeImports。设置 linter 为启用，并使用推荐规则。设置 formatter 为启用，indentStyle 为 space，indentWidth 为 2。在 javascript.formatter 下，将 quoteStyle 设为 single，将 semicolons 设为 always。

---

高级模式

如需全面的文档，包括高级异步模式、模块系统详情、性能优化和生产部署配置，请参阅：

• reference.md，包含完整的 API 参考、Context7 库映射和包管理器比较
• examples.md，包含可用于生产环境的代码示例、全栈模式和测试模板

Context7 集成

对于 Node.js 文档，使用 context7 获取 nodejs/node 库文档，并搜索 esm modules async 等主题。对于 Express，使用 expressjs/express，并搜索 middleware routing。对于 Fastify，使用 fastify/fastify，并搜索 plugins hooks。对于 Hono，使用 honojs/hono，并搜索 middleware validators。对于 Vitest，使用 vitest-dev/vitest，并搜索 mocking coverage。

---

适配良好的工具

• moai-lang-typescript，用于 TypeScript 集成以及通过 JSDoc 进行类型检查
• moai-domain-backend，用于 API 设计和微服务架构
• moai-domain-database，用于数据库集成和 ORM 模式
• moai-workflow-testing，用于 DDD 工作流和测试策略
• moai-foundation-quality，用于代码质量标准
• moai-essentials-debug，用于调试 JavaScript 应用程序

---

快速故障排查

模块系统问题：

检查 package.json 中的 type 字段。ESM 使用 type module，以及 import 和 export。CommonJS 使用 type commonjs，或省略该字段并使用 require 和 module.exports。

Node.js 版本检查：

运行 node 并使用版本标志，检查是否为 20.x 或 22.x LTS。运行 npm 并使用版本标志，检查是否为 10.x 或更高版本。

常见修复方法：

使用 force 标志运行 npm cache clean，以清除 npm 缓存。删除 node_modules 和 package-lock.json，然后运行 npm install。将 npm config prefix 设置为主目录下的 npm-global 文件夹，以解决权限问题。

ESM 与 CommonJS 互操作：

要从 ESM 导入 CommonJS，请导入默认导出，然后从中解构命名导出。在 CommonJS 中动态导入时，使用 await import，然后解构 default 属性。

---

最后更新：2026-01-11 状态：活跃（v1.2.0）