cf-memorypalace/.github/codeGeneration/javascript-base.instructions.md

---
applyTo: '**/*.js,!**/*.spec.js,!**/*.test.js'
---

# JavaScript Coding Standard Instructions

**Scope:** All `.js` files except test files (`.spec.js`, `.test.js`)
**Minimum Compatibility:** ECMAScript 2022 (ES13) or higher
**Module System:** ES Modules (ESM) - This workspace uses `"type": "module"` in `package.json`

## Summary Table

| Area           | Key Rules                                      |
|----------------|------------------------------------------------|
| Syntax         | ES2022+, ES modules, no `var`, Prettier        |
| Structure      | Pure/stateless, modular, DRY, named functions  |
| Features       | Arrow, destructuring, async/await, etc.        |
| Error Handling | try-catch, user-friendly errors, type checks   |
| Docs           | JSDoc/comments for public APIs                 |
| Accessibility  | Prefer semantic HTML, exceed WCAG & AODA where possible |
| **Module Format** | **Always use ES module imports/exports (import/export), never CommonJS (require/module.exports)** |

---

## CRITICAL: Module System

**This workspace uses ES Modules (ESM).** All `.js` files MUST use ES module syntax.

### ✅ ALWAYS USE (ES Modules):
```javascript
// Importing
import fs from 'fs';
import path from 'path';
import { execSync } from 'child_process';
import readline from 'readline';

// Exporting
export function myFunction() { }
export default MyClass;
export { helper1, helper2 };
```

### ❌ NEVER USE (CommonJS):
```javascript
// DO NOT USE THESE
const fs = require('fs');
const { execSync } = require('child_process');
module.exports = myFunction;
exports.helper = helper;
```

**Why:** The workspace `package.json` contains `"type": "module"`, which means Node.js treats all `.js` files as ES modules. Using `require()` will cause a `ReferenceError: require is not defined` error.

---

## 1. Formatting & Style

- [x] Use Prettier for formatting.
- [x] Use clear, descriptive variable and function names.
- [x] Prefer anonymous functions; avoid long named closures.
- [x] Write modular, reusable code (DRY principle).
- [x] Add comments to explain complex logic or design decisions.

**Example:**
```javascript
// Bad
function fetchData() { /* ... */ }

// Good
const fetchData = function() { /* ... */ }
```

---

## 2. Modern JavaScript Features (Use When Appropriate)

- [x] Use ES2022+ features:
  - Arrow functions
  - Template literals
  - Destructuring assignment
  - Spread/rest operators
  - Async/await for asynchronous code
  - Classes and inheritance (when OOP is needed)
  - Object shorthand notation
  - Optional chaining (`?.`)
  - Nullish coalescing (`??`)
  - Dynamic imports
  - BigInt for large integers
  - `Promise.allSettled()`
  - `String.prototype.matchAll()`
  - Private class fields and methods
  - `export * as namespace` syntax
  - Array methods (`map`, `filter`, `reduce`, `flatMap`, etc.)

**Example:**
```javascript
// Good
const [a, b] = arr;
const result = await fetchData();
const obj = { a, b };
```

---

## 3. Avoid

- [ ] `var` keyword (use `const` and `let` only)
- [ ] jQuery or external libraries unless absolutely necessary
- [ ] Callback-based async patterns (prefer Promises/async-await)
- [ ] Internet Explorer compatibility
- [ ] **CommonJS syntax (`require()`, `module.exports`) - ALWAYS use ES modules (`import`/`export`)**
- [ ] Use of `eval()` (security risk)

**Example:**
```javascript
// Bad - Will cause errors in this workspace
var x = 1;
const foo = require('foo');
module.exports = { foo };

// Good - ES Modules
const x = 1;
import foo from 'foo';
export { foo };
```

---

## 4. Performance & Structure

- [x] Use code splitting and dynamic imports for lazy loading when beneficial.
- [x] Minimize global variables and side effects.
- [x] Prefer pure functions and stateless modules where possible.

---

## 5. Error Handling

- [x] Use `try-catch` blocks for async/API calls; handle promise rejections explicitly.
- [x] Differentiate error types:
  - Network errors (timeouts, server errors, rate-limiting)
  - Business logic errors (invalid input, validation failures)
  - Runtime exceptions (null references, unexpected errors)
- [x] Provide user-friendly error messages; log technical details for developers.
- [x] Consider a central error handler or global event (e.g., `window.addEventListener('unhandledrejection')`).
- [x] Always validate and handle JSON responses and HTTP status codes.

**Example:**
```javascript
try {
  const data = await fetchData();
} catch (error) {
  // Handle error appropriately
}
```

---

## 6. Accessibility & Additional Best Practices

- [x] Use semantic HTML elements (e.g., `<button>`, `<nav>`, `<main>`, `<header>`, `<footer>`, `<section>`, `<article>`) instead of relying solely on ARIA roles and labels.
- [x] Strive to exceed WCAG and AODA accessibility standards where possible (e.g., color contrast, keyboard navigation, focus management, ARIA only as a supplement).
- [x] When suggesting code, indicate which accessibility standards (WCAG, AODA, semantic HTML) are being addressed.
- [x] Write code that is easily testable with unit tests.
- [x] Avoid magic numbers; use named constants.
- [x] Remove dead or unused code.
- [x] Use ES module syntax for imports/exports.
- [x] Document public APIs and exported functions with JSDoc or comments.

---

## Forbidden Patterns (Checklist)

- [ ] `var` keyword
- [ ] jQuery (unless absolutely necessary)
- [ ] Callback-based async
- [ ] `eval()`
- [ ] **CommonJS (`require()`, `module.exports`) - This workspace uses ES modules ONLY**
- [ ] Internet Explorer compatibility

**Remember:** Check `package.json` for `"type": "module"` - if present, ONLY use ES module syntax (`import`/`export`).

---

<!--
Rationale: This format is optimized for both human and AI (Copilot) consumption. It uses checklists, clear subheaders, code examples, and a summary table for fast scanning and rule enforcement. Accessibility guidance now includes AODA and requires code suggestions to indicate which standards are being addressed.
-->