javascript-idioms

JavaScript Idioms and Patterns

Modern JavaScript (ES2024+) rewards modules, async/await, and functional patterns. Idiomatic JS = strict mode, modular, well-tested.

Scope: Plain JavaScript only — projects with no tsconfig.json. This skill is intentionally thin: most JS guidance (coercion traps, async pitfalls, scope bugs, security, collections, performance) is shared with TypeScript and lives in one place to avoid divergence.

Loading guards:

• If tsconfig.json exists, do NOT load this skill — load @.agents/skills/typescript-idioms/SKILL.md instead. TypeScript is preferred whenever available.
• Coercion / async / scope / security / collection / performance pitfalls: see @.agents/skills/typescript-idioms/references/ts-patterns-and-anti-patterns.md — despite the filename, it is scoped to "TypeScript/JavaScript" and covers runtime pitfalls that apply to plain JS verbatim.
• Project layout: see @.agents/skills/typescript-idioms/references/project-structure.md (the generic backend/library/monorepo layouts are language-level, not TS-only).

Module System

1. ES modules over CommonJS for all new code:

   // ✅ ESM
   import { createTask } from './task-service.js';
   export function handler(req, res) { ... }
   
   // ❌ CommonJS (legacy only)
   const { createTask } = require('./task-service');
   

2. Always use .js extensions in ESM relative imports — Node.js ESM requires them; bundlers accept them.
3. package.json "type": "module" to enable ESM by default; use .cjs for any CommonJS holdouts.
4. CJS/ESM interop — import default from './cjs.cjs' works; named exports from CJS are not statically analyzable, prefer module.exports = { named } + const { named } = require(...) or migrate to ESM.

Declarations and Strict Mode

1. const by default, let when reassignment needed, never var. (var hoisting/closure bugs: see ts-patterns-and-anti-patterns.md §3.)
2. Enable strict mode — 'use strict'; at file top in scripts. Strict mode is implicit in ESM modules ("type": "module" in package.json) and class bodies.
3. Optional chaining and nullish coalescing (prefer ?? over || to avoid 0/'' falsy traps):

   const title = task?.title ?? 'Untitled';
   const count = config?.scoring?.default ?? 0;
   

4. Destructuring with defaults for clean parameter handling:

   function createTask({ title, priority = 'medium', tags = [] }) { ... }