---
name: aidd-javascript
description: JavaScript and TypeScript best practices and guidance. Use when writing, reviewing, or refactoring JavaScript or TypeScript code.
---

# JavaScript/TypeScript guide

Act as a top-tier software engineer with serious JavaScript/TypeScript discipline to carefully implement high quality software.

## Before Writing Code

- Read the lint and formatting rules.
- Observe the project's relevant existing code.
- Conform to existing code style, patterns, and conventions unless directed otherwise. Note: these instructions count as "directed otherwise" unless the user explicitly overrides them.

## Principles

- DOT
- YAGNI
- KISS
- DRY
- SDA - Self Describing APIs
- Simplicity - "Simplicity is removing the obvious, and adding the meaningful."
  - Obvious stuff gets hidden in the abstraction.
  - Meaningful stuff is what needs to be customized and passed in as parameters.
  - Functions should have default parameters whenever it makes sense so that callers can supply only what is different from the default.

Constraints {
  Be concise.
  Favor functional programming; keep functions short, pure, and composable.
  Favor map, filter, reduce over manual loops.
  Prefer immutability; use const, spread, and rest operators instead of mutation.
  One job per function; separate mapping from IO.
  Obey the projects lint and formatting rules.
  Omit needless code and variables; prefer composition with partial application and point-free style.
  Chain operations rather than introducing intermediate variables, e.g. `[x].filter(p).map(f)`
  Avoid loose procedural sequences; compose clear pipelines instead.
  Avoid `class` and `extends` as much as possible. Prefer composition of functions and data structures over inheritance.
  Keep related code together; group by feature, not by technical type.
  Put statements and expressions in positive form.
  Use parallel code for parallel concepts.
  Avoid null/undefined arguments; use options objects instead.
  Use concise syntax: arrow functions, object destructuring, array destructuring, template literals.
  Avoid verbose property assignments. bad: `const a = obj.a;` good: `const { a } = obj;`
  Assign reasonable defaults directly in function signatures.
    `const createExpectedUser = ({ id = createId(), name = '', description = '' } = {}) => ({ id, name, description });`
  Principle: SDA. This means:
  Parameter values should be explicitly named and expressed in function signatures:
    Bad: `const createUser = (payload = {}) => ({`
    Good: `const createUser = ({ id = createId(), name = '', description = ''} = {}) =>`
    Notice how default values also provide hints for type inference.
  Avoid IIFEs. Use block scopes, modules, or normal arrow functions instead. Principle: KISS
  Avoid using || for defaults. Use parameter defaults instead. See above.
  Prefer async/await or asyncPipe over raw promise chains.
  Use strict equality (===).
  Modularize by feature; one concern per file or function; prefer named exports.
}

NamingConstraints {
  Use active voice.
  Use clear, consistent naming.
  Functions should be verbs. e.g. `increment()`, `filter()`.
  Predicates and booleans should read like yes/no questions. e.g. `isActive`, `hasPermission`.
  Prefer standalone verbs over noun.method. e.g. `createUser()` not `User.create()`.
  Avoid noun-heavy and redundant names. e.g. `filter(fn, array)` not `matchingItemsFromArray(fn, array)`.
  Avoid "doSomething" style. e.g. `notify()` not `Notifier.doNotification()`.
  Lifecycle methods: prefer `beforeX` / `afterX` over `willX` / `didX`. e.g. `beforeUpdate()`.
  Use strong negatives over weak ones: `isEmpty(thing)` not `!isDefined(thing)`.
  Mixins and function decorators use `with${Thing}`. e.g. `withUser`, `withFeatures`, `withAuth`.
  Avoid ALL_CAPS for constants. Since we use functional programming, there's no need for a hard distinction between constants and variables.
}

Comments {
  Favor docblocks for public APIs - but keep them minimal.
  Ensure that any comments are necessary and add value. Never reiterate the style guides. Avoid obvious redundancy with the code, but short one-line comments that aid scannability are okay.
  Comments should stand-alone months or years later. Assume that the reader is not familiar with the task plan or epic.
}