javascript

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

JavaScript Core Knowledge

JavaScript核心知识

Deep Knowledge: Use
mcp__documentation__fetch_docs
with technology:
javascript
for comprehensive documentation.
深度资料:使用
mcp__documentation__fetch_docs
工具,指定technology为
javascript
以获取完整文档。

ES6+ Features

ES6+特性

javascript
// Destructuring
const { name, age = 18 } = user;
const [first, ...rest] = items;

// Spread operator
const merged = { ...defaults, ...options };
const combined = [...arr1, ...arr2];

// Template literals
const message = `Hello ${name}, you are ${age} years old`;

// Arrow functions
const add = (a, b) => a + b;
const fetchUser = async (id) => {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
};

// Optional chaining & nullish coalescing
const city = user?.address?.city ?? 'Unknown';

// Logical assignment
user.name ||= 'Anonymous';   // Assign if falsy
user.data ??= {};            // Assign if null/undefined
user.count &&= user.count++; // Assign if truthy
javascript
// Destructuring
const { name, age = 18 } = user;
const [first, ...rest] = items;

// Spread operator
const merged = { ...defaults, ...options };
const combined = [...arr1, ...arr2];

// Template literals
const message = `Hello ${name}, you are ${age} years old`;

// Arrow functions
const add = (a, b) => a + b;
const fetchUser = async (id) => {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
};

// Optional chaining & nullish coalescing
const city = user?.address?.city ?? 'Unknown';

// Logical assignment
user.name ||= 'Anonymous';   // Assign if falsy
user.data ??= {};            // Assign if null/undefined
user.count &&= user.count++; // Assign if truthy

Modules (ESM vs CommonJS)

模块(ESM与CommonJS)

javascript
// ESM (package.json: "type": "module")
import { readFile } from 'fs/promises';
import config from './config.js';
export const helper = () => {};
export default class Service {}

// CommonJS (default Node.js, .cjs)
const { readFile } = require('fs/promises');
const config = require('./config');
module.exports = { helper };
module.exports = Service;

// Dynamic imports (both)
const module = await import('./dynamic.js');
javascript
// ESM (package.json: "type": "module")
import { readFile } from 'fs/promises';
import config from './config.js';
export const helper = () => {};
export default class Service {}

// CommonJS (default Node.js, .cjs)
const { readFile } = require('fs/promises');
const config = require('./config');
module.exports = { helper };
module.exports = Service;

// Dynamic imports (both)
const module = await import('./dynamic.js');

Module Interop Issues

模块互操作问题

javascript
// Importing CommonJS from ESM
import pkg from 'cjs-package';       // Default export = module.exports
import { named } from 'cjs-package'; // May not work!

// Fix: use createRequire
import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const cjsModule = require('cjs-package');

// __dirname / __filename in ESM
import { fileURLToPath } from 'url';
import { dirname } from 'path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
javascript
// Importing CommonJS from ESM
import pkg from 'cjs-package';       // Default export = module.exports
import { named } from 'cjs-package'; // May not work!

// Fix: use createRequire
import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const cjsModule = require('cjs-package');

// __dirname / __filename in ESM
import { fileURLToPath } from 'url';
import { dirname } from 'path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

Async Patterns

异步模式

javascript
// Promises
fetch('/api/data')
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err))
  .finally(() => cleanup());

// Async/await
async function fetchData() {
  try {
    const response = await fetch('/api/data');
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return await response.json();
  } catch (error) {
    console.error('Fetch failed:', error);
    throw error;
  }
}

// Parallel execution
const [users, products] = await Promise.all([
  fetch('/api/users').then(r => r.json()),
  fetch('/api/products').then(r => r.json()),
]);

// Promise utilities
await Promise.allSettled(promises);  // Never rejects
const first = await Promise.race(promises);
const firstSuccess = await Promise.any(promises);
javascript
// Promises
fetch('/api/data')
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err))
  .finally(() => cleanup());

// Async/await
async function fetchData() {
  try {
    const response = await fetch('/api/data');
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return await response.json();
  } catch (error) {
    console.error('Fetch failed:', error);
    throw error;
  }
}

// Parallel execution
const [users, products] = await Promise.all([
  fetch('/api/users').then(r => r.json()),
  fetch('/api/products').then(r => r.json()),
]);

// Promise utilities
await Promise.allSettled(promises);  // Never rejects
const first = await Promise.race(promises);
const firstSuccess = await Promise.any(promises);

Array Methods

数组方法

javascript
// Transform
const doubled = items.map(x => x * 2);
const names = users.map(u => u.name);

// Filter
const adults = users.filter(u => u.age >= 18);
const unique = [...new Set(items)];

// Find
const user = users.find(u => u.id === id);
const index = users.findIndex(u => u.id === id);
const exists = users.some(u => u.active);
const allActive = users.every(u => u.active);

// Reduce
const total = items.reduce((sum, x) => sum + x, 0);
const grouped = items.reduce((acc, item) => {
  (acc[item.category] ||= []).push(item);
  return acc;
}, {});

// Flat & FlatMap
const flat = [[1, 2], [3, 4]].flat();
const expanded = users.flatMap(u => u.orders);

// At (negative indexing)
const last = items.at(-1);
const secondLast = items.at(-2);
javascript
// Transform
const doubled = items.map(x => x * 2);
const names = users.map(u => u.name);

// Filter
const adults = users.filter(u => u.age >= 18);
const unique = [...new Set(items)];

// Find
const user = users.find(u => u.id === id);
const index = users.findIndex(u => u.id === id);
const exists = users.some(u => u.active);
const allActive = users.every(u => u.active);

// Reduce
const total = items.reduce((sum, x) => sum + x, 0);
const grouped = items.reduce((acc, item) => {
  (acc[item.category] ||= []).push(item);
  return acc;
}, {});

// Flat & FlatMap
const flat = [[1, 2], [3, 4]].flat();
const expanded = users.flatMap(u => u.orders);

// At (negative indexing)
const last = items.at(-1);
const secondLast = items.at(-2);

Object Methods

对象方法

javascript
// Entries/Keys/Values
Object.keys(obj);    // ['a', 'b']
Object.values(obj);  // [1, 2]
Object.entries(obj); // [['a', 1], ['b', 2]]

// From entries
const obj = Object.fromEntries([['a', 1], ['b', 2]]);

// Assign & spread
const merged = Object.assign({}, defaults, options);
const merged2 = { ...defaults, ...options };

// Property descriptors
Object.defineProperty(obj, 'readonly', {
  value: 42,
  writable: false,
  enumerable: true,
});

// Freeze/Seal
Object.freeze(obj);  // No changes at all
Object.seal(obj);    // No add/delete, can modify
javascript
// Entries/Keys/Values
Object.keys(obj);    // ['a', 'b']
Object.values(obj);  // [1, 2]
Object.entries(obj); // [['a', 1], ['b', 2]]

// From entries
const obj = Object.fromEntries([['a', 1], ['b', 2]]);

// Assign & spread
const merged = Object.assign({}, defaults, options);
const merged2 = { ...defaults, ...options };

// Property descriptors
Object.defineProperty(obj, 'readonly', {
  value: 42,
  writable: false,
  enumerable: true,
});

// Freeze/Seal
Object.freeze(obj);  // No changes at all
Object.seal(obj);    // No add/delete, can modify

Classes

javascript
class Service {
  #privateField = 'secret';  // Private field
  static count = 0;          // Static field

  constructor(name) {
    this.name = name;
    Service.count++;
  }

  // Instance method
  greet() {
    return `Hello, ${this.name}`;
  }

  // Private method
  #validate() {
    return this.#privateField.length > 0;
  }

  // Getter/Setter
  get upperName() {
    return this.name.toUpperCase();
  }

  set upperName(value) {
    this.name = value.toLowerCase();
  }

  // Static method
  static getCount() {
    return Service.count;
  }
}

// Inheritance
class Admin extends Service {
  constructor(name, role) {
    super(name);
    this.role = role;
  }
}
javascript
class Service {
  #privateField = 'secret';  // Private field
  static count = 0;          // Static field

  constructor(name) {
    this.name = name;
    Service.count++;
  }

  // Instance method
  greet() {
    return `Hello, ${this.name}`;
  }

  // Private method
  #validate() {
    return this.#privateField.length > 0;
  }

  // Getter/Setter
  get upperName() {
    return this.name.toUpperCase();
  }

  set upperName(value) {
    this.name = value.toLowerCase();
  }

  // Static method
  static getCount() {
    return Service.count;
  }
}

// Inheritance
class Admin extends Service {
  constructor(name, role) {
    super(name);
    this.role = role;
  }
}

Error Handling

错误处理

javascript
// Custom error
class ValidationError extends Error {
  constructor(message, field) {
    super(message);
    this.name = 'ValidationError';
    this.field = field;
  }
}

// Try/catch with specific handling
try {
  const data = JSON.parse(input);
} catch (error) {
  if (error instanceof SyntaxError) {
    console.error('Invalid JSON');
  } else if (error instanceof ValidationError) {
    console.error(`Validation failed: ${error.field}`);
  } else {
    throw error; // Re-throw unknown errors
  }
}

// Error cause (ES2022)
try {
  await fetchData();
} catch (error) {
  throw new Error('Failed to load data', { cause: error });
}

javascript
// Custom error
class ValidationError extends Error {
  constructor(message, field) {
    super(message);
    this.name = 'ValidationError';
    this.field = field;
  }
}

// Try/catch with specific handling
try {
  const data = JSON.parse(input);
} catch (error) {
  if (error instanceof SyntaxError) {
    console.error('Invalid JSON');
  } else if (error instanceof ValidationError) {
    console.error(`Validation failed: ${error.field}`);
  } else {
    throw error; // Re-throw unknown errors
  }
}

// Error cause (ES2022)
try {
  await fetchData();
} catch (error) {
  throw new Error('Failed to load data', { cause: error });
}

When NOT to Use This Skill

不适用场景

ScenarioUse Instead
TypeScript project
typescript
skill
Node.js runtime internals
nodejs
skill
Frontend frameworks
frontend-react
,
frontend-vue
, etc.
Build tooling
vite
,
webpack
, etc. skills
Testing
testing-vitest
,
testing-jest
skills

场景替代技能
TypeScript项目
typescript
技能
Node.js运行时内部机制
nodejs
技能
前端框架相关
frontend-react
frontend-vue
等技能
构建工具相关
vite
webpack
等技能
测试相关
testing-vitest
testing-jest
等技能

Anti-Patterns

反模式

Anti-PatternWhy It's BadCorrect Approach
Using
var
Function scope, hoisting issuesUse
const
or
let
==
instead of
===
Type coercion bugsAlways use
===
Mutating function parametersSide effects, hard to debugReturn new object/array
Missing
await
on Promise
Unhandled rejectionsAlways await or .catch()
Mixing ESM and CommonJSModule system conflictsChoose one, prefer ESM
Callback hellUnreadable codeUse async/await
Not handling Promise rejectionsSilent failuresAdd .catch() or try/catch
Global variablesNamespace pollutionUse modules

反模式问题所在正确做法
使用
var
函数作用域、变量提升问题使用
const
let
使用
==
而非
===
类型隐式转换导致bug始终使用
===
修改函数参数副作用、难以调试返回新的对象/数组
未在Promise上使用
await
未处理的拒绝始终使用await或.catch()
混合使用ESM与CommonJS模块系统冲突选择一种,优先使用ESM
回调地狱代码可读性差使用async/await
未处理Promise拒绝静默失败添加.catch()或try/catch
全局变量命名空间污染使用模块

Quick Troubleshooting

快速排查指南

IssueCauseSolution
"X is not defined"Variable not declaredCheck spelling, imports
"Cannot read property of undefined"Object is undefinedUse optional chaining ?.
"Promise rejected but not handled"Missing .catch()Add error handling
"Module not found"Wrong import pathCheck file path, extension
"Unexpected token"Syntax errorCheck for missing brackets, commas
"This is undefined"Arrow function contextUse regular function or bind
Memory leak in event listenersNot removing listenersUse removeEventListener
Slow performance with large arraysInefficient algorithmsUse appropriate data structures

问题原因解决方案
"X is not defined"变量未声明检查拼写、导入语句
"Cannot read property of undefined"对象为undefined使用可选链操作符?.
"Promise rejected but not handled"缺少.catch()添加错误处理
"Module not found"导入路径错误检查文件路径、扩展名
"Unexpected token"语法错误检查是否缺少括号、逗号
"This is undefined"箭头函数上下文问题使用普通函数或bind
事件监听器导致内存泄漏未移除监听器使用removeEventListener
大型数组操作性能慢算法效率低使用合适的数据结构

When to Use JS vs TypeScript

JavaScript与TypeScript选型建议

ScenarioChoice
New projectTypeScript
Quick scriptsJavaScript
Legacy codebaseJavaScript (gradual migration)
Public librariesTypeScript with .d.ts
Prototype/MVPJavaScript ok

场景选择
新项目TypeScript
快速脚本JavaScript
遗留代码库JavaScript(逐步迁移)
公共库TypeScript(附带.d.ts文件)
原型/最小可行产品(MVP)JavaScript可满足需求

Reference Documentation

参考文档

Deep Knowledge: Use
mcp__documentation__fetch_docs
with technology:
javascript
for comprehensive documentation.
深度资料:使用
mcp__documentation__fetch_docs
工具,指定technology为
javascript
以获取完整文档。