# Writing Idiomatic JavaScript with Clear Intent

> Use idiomatic JavaScript to make intent visible through clear collection transforms, explicit guards, and local conventions rather than compact but opaque expressions.

- Canonical HTML: [https://unrust.dev/languages/javascript/idiomatic-code](https://unrust.dev/languages/javascript/idiomatic-code)
- Markdown representation: [https://unrust.dev/languages/javascript/idiomatic-code/index.md](https://unrust.dev/languages/javascript/idiomatic-code/index.md)

Published: 2026-07-14

## Direct answer

Idiomatic JavaScript uses familiar language and repository patterns to make behavior easy to inspect: clear guards, deliberate array transformations, readable async control flow, and explicit handling of nullable data where it matters. An idiom is not a rule to compress every operation into one expression. Prefer the form that lets a teammate predict state, errors, and ownership in the surrounding codebase.

## Use expressive transforms when they preserve the contract

Methods such as map, filter, find, and some reduce calls can communicate collection intent quickly, but they should not bury a business rule or error condition. If a chain makes ordering, mutation, or a fallback hard to explain, a small named loop or helper may be more idiomatic for that repository.

## Let the codebase set the local dialect

JavaScript supports many valid styles for modules, async work, validation, and state updates. Read nearby code, lint rules, and tests before introducing a new pattern, then explain any departure in terms of a concrete safety or readability benefit rather than personal preference.

## Original example

### Keep a transformation and its policy visible

```javascript
const enabledFeatureIds = features
  .filter((feature) => feature.enabled)
  .map((feature) => feature.id);
```

This concise original example is easy to read when enabled and id are the full policy. If the code must log excluded features, normalize missing ids, or preserve a particular order, that behavior deserves explicit structure rather than being hidden inside a cleverer chain. Local tests should make that choice observable.

## Checklist

- Can a reader see the collection policy without decoding unrelated expression tricks?
- Does this JavaScript form hide a mutation, error path, or business rule?
- Does surrounding code use the same async and null-handling convention?

## Practice loop

1. Find a nested JavaScript conditional and write the clearest guard-clause version you can justify.
2. Compare a collection method chain with a named loop for the same behavior and note which exposes errors better.
3. Check nearby code and tests before calling a valid pattern idiomatic for this repository.

## Limits of this page

Idiomatic JavaScript changes across runtimes, teams, and performance constraints, so there is no universal style score. A timed comparison can support a discussion about clarity, but it cannot establish that one person is more capable or explain why a convention was unfamiliar.

## Source context

Editorially reviewed for Unrust using public language documentation, common code-review practice, and small original examples written for this resource system.

## Related resources

- [How to Prepare for a Focused Code Review](https://unrust.dev/use-cases/prepare-for-code-review/index.md): Prepare a small, evidence-rich code review by clarifying the contract, reducing unrelated changes, and showing tests that cover the risky behavior.
- [How to Test an AI-Suggested Refactor](https://unrust.dev/use-cases/test-an-ai-suggested-refactor/index.md): Test an AI-suggested refactor by preserving observable behavior, specifying invariants, and comparing before-and-after cases instead of trusting cleaner-looking code.

Next step: [Take the free diagnostic](https://unrust.dev/diagnostic/index.md)