aidd-javascript

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. }