modern-javascript

Modern JavaScript

Use current JavaScript without confusing specification status, runtime support, and toolchain support. Treat these as three separate questions:

1. Is it standardized? Check the frozen annual ECMA-262 edition or TC39's current proposal tracker.
2. Does the target run it? Check the project's declared Node/browser targets and current compatibility data.
3. Can tooling bridge the gap? Syntax may need a transform; built-ins need a polyfill. One does not imply the other.

Workflow

1. Inspect package.json (engines, browserslist, dependencies), runtime/deployment config, tsconfig.json, and Babel/bundler config. Do not invent a baseline.
2. Select the simplest standardized feature supported by that baseline.
3. For a newer standard or mature proposal, state the required runtime, transform, or polyfill in the implementation or handoff.
4. Preserve observable behavior while modernizing: mutation, evaluation order, iterator consumption, concurrency, cancellation, property descriptors, and error propagation matter more than shorter syntax.
5. Run the project's formatter, type-checker, linter, and tests. Exercise both the native path and compatibility path when both ship.

Read references/COMPATIBILITY.md whenever support is uncertain, the feature is newer than ES2023, or a proposal is involved.

Status Rules

• Use the frozen ECMAScript 2026 specification for ES2026 attribution and the living draft for already-integrated future features.
• Use TC39's finished-proposals table for Stage 4 publication-year mapping and its active tracker for current stages.
• Do not infer an edition from the year a browser shipped a feature. Array.fromAsync, for example, shipped before its ES2026 publication.
• Do not describe Stage 3 or 2.7 syntax as standard JavaScript. It can still be a sound project choice when a maintained toolchain implements the selected proposal revision.
• Do not emit withdrawn Records & Tuples syntax (#{} / #[]).

Edition Map

This is a routing index, not a substitute for the detailed references.

Already Stage 4 with publication expected in ES2027: Temporal, explicit resource management (using / await using), Atomics.pause, and Iterator.zip / zipKeyed. See references/UPCOMING.md.

Choose by Semantics

Collections

Do not replace mutation mechanically. A private, newly allocated array can be mutated efficiently without exposing mutable shared state. Use change-by-copy methods when preserving the source is part of the contract.

const ranked = scores.toSorted((a, b) => b.points - a.points);

const byTeam = Object.groupBy(players, player => player.team);
if (Object.hasOwn(byTeam, requestedTeam)) {
  render(byTeam[requestedTeam]);
}

Nullish and Property Checks

const city = user?.address?.city ?? 'Unknown';

// `??` preserves 0, false, and ''. Use `||` only when all falsy values mean absent.
settings.timeout ??= 5_000;

// Safe for overwritten or null-prototype objects.
if (Object.hasOwn(record, 'id')) use(record.id);

Async Work

// Independent work: concurrent.
const [user, permissions] = await Promise.all([
  fetchUser(id),
  fetchPermissions(id),
]);

// Ordered source: sequential consumption.
const pages = await Array.fromAsync(fetchPages());

// A loop is correct when each step depends on the previous one.
for (const migration of migrations) {
  await migration.run();
}

Never use forEach(async () => ...) when completion must be awaited. Read references/PROMISES.md for combinators and references/CONCURRENCY.md for bounded concurrency and cancellation.

Modules

Use with for import attributes; the older assert spelling is not current ECMAScript.

import config from './config.json' with { type: 'json' };

const locale = await import(`./locales/${language}.js`);

Import attributes and JSON modules are ES2025, but module loading remains host-sensitive. Verify Node, browser, bundler, and test-runner support together.

Exact API Boundaries

• structuredClone, fetch, streams, AbortController, and DOM APIs are host/web APIs, not ECMA-262 language features.
• Intl.* is standardized in ECMA-402, not ECMA-262.
• TypeScript syntax and types are not JavaScript runtime features.
• A TypeScript lib entry supplies type declarations, not a runtime implementation.
• Babel syntax transforms do not automatically install missing globals or prototype methods.

Compatibility Paths

Prefer native support when the target has it. Otherwise choose deliberately:

TypeScript 7.0 is released, but it is not a polyfill and 7.0 has no stable programmatic compiler API. Projects whose framework/linter embeds TypeScript may need TypeScript 6 alongside it. See references/COMPATIBILITY.md.

Review Traps

• .sort(), .reverse(), .splice(), Map#set, Set#add, and most TypedArray methods mutate. That is not automatically wrong; make it intentional.
• Object/array spread is shallow and invokes ordinary property access; it does not preserve prototypes or descriptors.
• structuredClone is a host API and cannot clone functions, weak collections, or every platform object.
• Object.groupBy has no inherited hasOwnProperty or toString.
• Iterator helpers are lazy and single-pass; arrays are reusable and eager.
• Promise.all does not cancel remaining operations after rejection. Pass AbortSignal when cancellation is required.
• Math.sumPrecise accurately sums the binary Number inputs; it does not make decimal money exact.
• Error.isError is cross-realm-safe for ECMAScript Error objects; host error types can have runtime-specific behavior.
• Temporal is not part of ES2026. Its Stage 4 publication target is ES2027.
• Standard decorators are not legacy TypeScript experimentalDecorators.

References

Load only what the task needs.

Authority Order

1. Frozen annual ECMA-262 editions for edition membership
2. Living ECMA-262 plus TC39 proposal tracker/spec repositories for future status and semantics
3. Test262 for conformance cases
4. MDN Browser Compatibility Data and official engine/runtime releases for availability
5. Official TypeScript, Babel, and polyfill documentation for compatibility paths