version: "1.0.0" 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. }