Applying Alibaba Node.js Conventions

Apply these conventions when writing or reviewing Node.js code:

JavaScript
// ✅ Good: destructure built-in globals, promises API, proper import order, native Error
const fs = require('fs').promises;
const http = require('http');

const moment = require('moment');

const Car = require('./models/car');

async function readConfig(path) {
  try {
    return await fs.readFile(path, 'utf8');
  } catch (err) {
    throw err; // never throw a literal
  }
}

Supported Node.js versions: Current, Active LTS, Maintenance LTS only. Never target Unstable/EOL versions, and avoid odd-numbered versions (19, 21, 23) in production — their support window is only 6 months.

When reviewing/writing Node.js code, check in this order:

Progress:
- [ ] 1. Verify Node.js version target (LTS/Current only, avoid odd versions)
- [ ] 2. Check coding style (globals, promises, import order, error throwing, no sync I/O)
- [ ] 3. Check security rules (error leakage, headers, JSONP, auth, SQL injection, uploads, redirects, input validation)
- [ ] 4. Check best practices (statelessness, static files, CPU-bound tasks, async/await, monitoring)
- [ ] 5. Recommend eslint-config-ali/node (or /typescript/node) for automated enforcement

1. Coding Style

• Prefer built-in globals over require-ing them explicitly where Node exposes globals (Buffer, URL, URLSearchParams, TextEncoder, TextDecoder, process, console). ESLint: node/prefer-global.
• Prefer built-in promise APIs over callback style: require('dns').promises, require('fs').promises (Node ≥ v11.14.0). ESLint: node/prefer-promises.
• Import order (ESLint: import/order), each group separated by a blank line, alphabetical within group (destructured imports sorted by first named import, and internally):
  1. Node built-in modules
  2. npm packages
  3. Local files (relative paths)
• Throw only Error objects/instances, never literals, strings, or undefined. ESLint: no-throw-literal.
• Never use sync methods (fs.readFileSync, child_process.execSync, etc.) in production code paths — they block the event loop. Use fs.promises or a library like mz.

2. Security Rules (mandatory unless noted "recommended")

3. Best Practices

• Stateless services: use external stores; killing an instance must not lose data.
• Don't serve static files from Node — offload to CDN to avoid blocking other request handling.
• Delegate CPU-intensive work (gzip, TLS termination) to a reverse proxy (nginx) rather than doing it in Node.
• Prefer async/await over raw callbacks/promise chains to avoid callback hell and simplify error handling.
• Use util.promisify to convert callback-style APIs:

  JavaScript
  const util = require('util');
  const fs = require('fs');
  const stat = util.promisify(fs.stat);

• Use native Promise, not third-party libraries like bluebird.
• Return this from instance methods to enable method chaining:

  JavaScript
  class Jedi {
    jump() { this.jumping = true; return this; }
    setHeight(h) { this.height = h; return this; }
  }

• Use a Node.js performance monitoring tool (e.g., Alibaba Cloud Node.js Performance Platform) for APM, heap snapshots, dependency/security alerts, and slow-HTTP/error logging.