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

applyTo

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):

// 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):

// 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

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

Example:

// Bad
function fetchData() { /* ... */ }

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

---

2. Modern JavaScript Features (Use When Appropriate)

• 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:

// 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:

// 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

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

---

5. Error Handling

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

Example:

try {
  const data = await fetchData();
} catch (error) {
  // Handle error appropriately
}

---

6. Accessibility & Additional Best Practices

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

---