eslint-plugin-nextfriday 1.5.3 → 1.7.0

package/docs/rules/JSX_NO_VARIABLE_IN_CALLBACK.md

@@ -0,0 +1,144 @@
+# jsx-no-variable-in-callback
+
+Disallow variable declarations inside callback functions within JSX.
+
+## Rule Details
+
+This rule prevents variable declarations inside callback functions that are directly used within JSX expressions. This enforces cleaner, more maintainable code by extracting complex logic to separate functions.
+
+### Why?
+
+1. **Readability**: Keeps JSX clean and focused on rendering, not logic
+2. **Maintainability**: Extracted functions are easier to test and modify
+3. **Separation of Concerns**: Logic belongs in functions, not inline in JSX
+4. **Consistency**: Enforces a uniform pattern across the codebase
+
+## Examples
+
+### ❌ Incorrect
+
+```tsx
+// Bad: Variable declared inside map callback in JSX
+const UserList = ({ users }) => {
+  return (
+    <div>
+      {users.map((user) => {
+        const displayName = user.firstName + " " + user.lastName;
+        return <div key={user.id}>{displayName}</div>;
+      })}
+    </div>
+  );
+};
+```
+
+```tsx
+// Bad: Variable in filter callback
+const ProductList = ({ products }) => {
+  return (
+    <ul>
+      {products.filter((product) => {
+        const isAvailable = product.stock > 0 && product.active;
+        return isAvailable;
+      })}
+    </ul>
+  );
+};
+```
+
+```tsx
+// Bad: Multiple variables in callback
+const OrderSummary = ({ orders }) => {
+  return (
+    <div>
+      {orders.map((order) => {
+        const total = order.price * order.quantity;
+        const discount = total * 0.1;
+        const final = total - discount;
+        return <div key={order.id}>{final}</div>;
+      })}
+    </div>
+  );
+};
+```
+
+### ✅ Correct
+
+```tsx
+// Good: Extract logic to a separate function
+const UserList = ({ users }) => {
+  const renderUsers = () =>
+    users.map((user) => {
+      const displayName = user.firstName + " " + user.lastName;
+      return <div key={user.id}>{displayName}</div>;
+    });
+
+  return <div>{renderUsers()}</div>;
+};
+```
+
+```tsx
+// Good: Use helper function outside JSX
+const ProductList = ({ products }) => {
+  const isProductAvailable = (product) => {
+    const isAvailable = product.stock > 0 && product.active;
+    return isAvailable;
+  };
+
+  return <ul>{products.filter(isProductAvailable)}</ul>;
+};
+```
+
+```tsx
+// Good: No variable declaration in callback
+const UserList = ({ users }) => {
+  return (
+    <div>
+      {users.map((user) => (
+        <div key={user.id}>
+          {user.firstName} {user.lastName}
+        </div>
+      ))}
+    </div>
+  );
+};
+```
+
+```tsx
+// Good: Variable declared outside JSX
+const OrderSummary = ({ orders }) => {
+  const discount = 0.1;
+
+  return (
+    <div>
+      {orders.map((order) => {
+        const total = order.price * order.quantity;
+        return <div key={order.id}>{total - total * discount}</div>;
+      })}
+    </div>
+  );
+};
+```
+
+```tsx
+// Good: Extract rendering to a function
+const OrderSummary = ({ orders }) => {
+  const calculateFinalPrice = (order) => {
+    const total = order.price * order.quantity;
+    const discount = total * 0.1;
+    return total - discount;
+  };
+
+  const renderOrders = () => orders.map((order) => <div key={order.id}>{calculateFinalPrice(order)}</div>);
+
+  return <div>{renderOrders()}</div>;
+};
+```
+
+## When Not To Use It
+
+If you prefer keeping all logic inline within JSX callbacks and don't mind the reduced readability, you can disable this rule. However, this is generally not recommended as it leads to harder-to-maintain code.
+
+## Further Reading
+
+- [React Component Best Practices](https://react.dev/learn/keeping-components-pure)
+- [Clean Code Principles](https://clean-code-developer.com/)

package/docs/rules/NO_DIRECT_DATE.md

@@ -0,0 +1,36 @@
+# no-direct-date
+
+Disallow direct usage of Date constructor and methods to enforce centralized date utilities.
+
+## Rule Details
+
+This rule prevents the use of the native JavaScript `Date` constructor and its static methods (`Date.now()`, `Date.parse()`). Using a centralized date utility library like dayjs, date-fns, or Luxon provides better consistency, easier testing, and more predictable date handling across your application.
+
+## Examples
+
+**Incorrect** code for this rule:
+
+```js
+const now = new Date();
+const timestamp = Date.now();
+const parsed = Date.parse("2024-01-01");
+const specificDate = new Date("2024-01-01");
+const dateFromTimestamp = new Date(1704067200000);
+const dateFromParts = new Date(2024, 0, 1);
+```
+
+**Correct** code for this rule:
+
+```js
+import dayjs from "dayjs";
+
+const now = dayjs();
+const timestamp = dayjs().valueOf();
+const parsed = dayjs("2024-01-01");
+const specificDate = dayjs("2024-01-01");
+const dateFromTimestamp = dayjs(1704067200000);
+```
+
+## When Not To Use It
+
+If your project does not use a centralized date utility library and you prefer to work directly with the native JavaScript Date API, you can disable this rule.

package/docs/rules/NO_SINGLE_CHAR_VARIABLES.md

@@ -0,0 +1,108 @@
+# no-single-char-variables
+
+Disallow single character variable and parameter names for better code readability.
+
+## Rule Details
+
+This rule enforces descriptive variable and parameter names by disallowing single character identifiers. Single character names like `d`, `u`, `l`, `r` are cryptic and make code harder to understand. They require readers to guess or track what each variable represents.
+
+**Incorrect** code for this rule:
+
+```typescript
+const d = new Date();
+const u = await getUser();
+const l = list.length;
+const r = await fetch(url);
+
+users.map((u) => u.id);
+onClick((e) => e.preventDefault());
+
+const add = (a, b) => a + b;
+const e = (x) => x * 2;
+
+function f() {
+  return 1;
+}
+
+const { a } = obj;
+const [x] = array;
+
+try {
+} catch (e) {}
+```
+
+**Correct** code for this rule:
+
+```typescript
+const currentDate = new Date();
+const currentUser = await getUser();
+const itemCount = list.length;
+const response = await fetch(url);
+
+users.map((user) => user.id);
+onClick((event) => event.preventDefault());
+
+const add = (val1, val2) => val1 + val2;
+const add = (width, height) => width * height;
+const calculateDouble = (value) => value * 2;
+
+function getName() {
+  return "test";
+}
+
+const { alpha } = obj;
+const { a: alpha } = obj;
+const [first] = array;
+
+try {
+} catch (error) {}
+```
+
+## Exceptions
+
+The rule allows the following exceptions:
+
+### Loop Counters
+
+Single character loop counters `i`, `j`, `k`, `n` are allowed in traditional for loops:
+
+```typescript
+for (let i = 0; i < 10; i++) {}
+for (let j = 0; j < items.length; j++) {}
+for (let i = 0, j = 10; i < j; i++, j--) {}
+```
+
+Note: These are only allowed in traditional `for` loops, not in `for...of` or `for...in` loops.
+
+### Underscore for Unused Variables
+
+A single underscore `_` is allowed to indicate intentionally unused variables:
+
+```typescript
+const _ = unusedValue;
+const [_, second] = array;
+array.map((_, index) => index);
+```
+
+## Benefits
+
+- **Self-documenting code**: Descriptive names make code readable without additional comments
+- **Reduced cognitive load**: No need to track or guess what single letters represent
+- **Better IDE support**: Meaningful names provide better autocomplete and search results
+- **Easier debugging**: Clear variable names make debugging and code review faster
+- **Improved collaboration**: Team members can understand code without additional context
+
+## When Not To Use
+
+- For very short scripts or throwaway code
+- When working with mathematical formulas where single letters are conventional (e.g., `x`, `y` for coordinates)
+- In legacy codebases where this pattern is established and changing would be disruptive
+
+## Configuration
+
+This rule has no configuration options.
+
+## Related Rules
+
+- [prefer-destructuring-params](./PREFER_DESTRUCTURING_PARAMS.md) - Encourages destructuring for function parameters
+- [prefer-named-param-types](./PREFER_NAMED_PARAM_TYPES.md) - Encourages named parameters for better readability

package/docs/rules/PREFER_FUNCTION_DECLARATION.md

@@ -0,0 +1,139 @@
+# prefer-function-declaration
+
+Enforce function declarations over arrow functions assigned to variables in `.ts` files for better readability and hoisting.
+
+## Rule Details
+
+This rule requires using function declarations instead of arrow functions or function expressions when defining named functions in TypeScript utility files. Arrow functions used as callbacks (in `.map()`, `.filter()`, etc.) are still allowed.
+
+**Target:** `.ts` files only (not `.tsx`, `.js`, or `.d.ts`)
+
+**Incorrect** code for this rule:
+
+```typescript
+// utils/date.ts
+const formatThaiDate = (date: Date) => {
+  return date.toLocaleDateString("th-TH");
+};
+
+const formatDate = (date: Date) => date.toISOString();
+
+export const add = (a: number, b: number) => a + b;
+
+const greet = function (name: string) {
+  return `Hello ${name}`;
+};
+
+const fetchUser = async (id: string) => {
+  return await api.get(`/users/${id}`);
+};
+```
+
+**Correct** code for this rule:
+
+```typescript
+// utils/date.ts
+function formatThaiDate(date: Date) {
+  return date.toLocaleDateString("th-TH");
+}
+
+function formatDate(date: Date) {
+  return date.toISOString();
+}
+
+export function add(a: number, b: number) {
+  return a + b;
+}
+
+function greet(name: string) {
+  return `Hello ${name}`;
+}
+
+async function fetchUser(id: string) {
+  return await api.get(`/users/${id}`);
+}
+```
+
+## What This Rule Allows
+
+Arrow functions are still allowed in the following contexts:
+
+### Callbacks
+
+```typescript
+// All of these are allowed
+const years = dates.map((date) => date.getFullYear());
+const active = items.filter((item) => item.active);
+const sorted = items.sort((a, b) => a.name.localeCompare(b.name));
+items.forEach((item) => console.log(item));
+const total = items.reduce((sum, item) => sum + item.price, 0);
+setTimeout(() => console.log("done"), 1000);
+promise.then((result) => result.data);
+```
+
+### Object Properties
+
+```typescript
+const handler = {
+  onClick: () => console.log("clicked"),
+  onHover: () => setHovered(true),
+};
+```
+
+### Array Elements
+
+```typescript
+const callbacks = [() => 1, () => 2, () => 3];
+```
+
+### Return Values
+
+```typescript
+function createHandler() {
+  return () => console.log("handled");
+}
+```
+
+### Conditional/Logical Expressions
+
+```typescript
+const fn = condition ? () => valueA : () => valueB;
+const handler = defaultFn || (() => fallback);
+```
+
+### TSX Files
+
+```typescript
+// components/Button.tsx - Arrow functions allowed
+const Button = () => <button>Click me</button>;
+const handleClick = () => console.log("clicked");
+```
+
+## Benefits
+
+- **Hoisting**: Function declarations are hoisted, allowing you to call functions before they're defined
+- **Better readability**: Function declarations are more explicit about intent
+- **Clearer stack traces**: Named function declarations provide better debugging information
+- **Consistent style**: Enforces uniform function definition patterns in utility files
+- **Self-documenting**: `function formatDate()` is clearer than `const formatDate = () =>`
+
+## Why Only `.ts` Files?
+
+- **`.tsx` files**: Arrow functions are commonly used for React components and event handlers
+- **`.js` files**: JavaScript projects may have different conventions
+- **`.d.ts` files**: Declaration files don't contain implementations
+
+## When Not To Use
+
+- When you prefer arrow functions for all function definitions
+- In projects where arrow function style is established
+- When you need lexical `this` binding (arrow functions don't have their own `this`)
+
+## Configuration
+
+This rule has no configuration options.
+
+## Related Rules
+
+- [func-style](https://eslint.org/docs/rules/func-style) - Built-in ESLint rule for function style
+- [arrow-body-style](https://eslint.org/docs/rules/arrow-body-style) - Enforce arrow function body style

package/docs/rules/PREFER_JSX_TEMPLATE_LITERALS.md

@@ -0,0 +1,78 @@
+# prefer-jsx-template-literals
+
+Enforce using template literals instead of mixing text and JSX expressions.
+
+## Rule Details
+
+This rule prevents mixing plain text with JSX expressions in JSX elements, which can lead to incorrect spacing and readability issues. Instead, it enforces using template literals to combine text and expressions.
+
+### Why?
+
+Mixing text and JSX expressions without proper spacing can cause:
+
+1. **Spacing issues**: `<div>+ {value}</div>` renders as "+ value" with unexpected spacing
+2. **Inconsistent formatting**: Hard to maintain consistent spacing across the codebase
+3. **Readability problems**: Mixed syntax makes code harder to read and understand
+
+Using template literals ensures:
+
+- Explicit control over spacing
+- Consistent formatting
+- Better readability
+- Easier to maintain
+
+## Examples
+
+### ❌ Incorrect
+
+```tsx
+// Bad: Text followed by expression
+<div>+ {fooVariable}</div>
+<div>+{fooVariable}</div>
+<div>Price: {price}</div>
+<div>$ {amount}</div>
+<span>Total: {total}</span>
+<p>Hello {name}</p>
+
+// Bad: Expression followed by text
+<div>{count} items</div>
+<div>{price}$</div>
+```
+
+### ✅ Correct
+
+```tsx
+// Good: Using template literals
+<div>{`+${fooVariable}`}</div>
+<div>{`+ ${fooVariable}`}</div>
+<div>{`Price: ${price}`}</div>
+<div>{`$ ${amount}`}</div>
+<span>{`Total: ${total}`}</span>
+<p>{`Hello ${name}`}</p>
+
+// Good: Using template literals for expression + text
+<div>{`${count}items`}</div>
+<div>{`${price}$`}</div>
+
+// Good: Expression only
+<div>{fooVariable}</div>
+<div>{price}</div>
+
+// Good: Text only
+<div>Some static text</div>
+
+// Good: Expression with whitespace only around it
+<div>  {fooVariable}  </div>
+<div>
+  {fooVariable}
+</div>
+```
+
+## When Not To Use It
+
+If you prefer mixing text and JSX expressions, you can disable this rule. However, this may lead to inconsistent spacing and formatting issues.
+
+## Further Reading
+
+- [Template Literals (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+- [JSX in React](https://react.dev/learn/writing-markup-with-jsx)

package/docs/rules/REQUIRE_EXPLICIT_RETURN_TYPE.md

@@ -0,0 +1,130 @@
+# require-explicit-return-type
+
+Require explicit return types on functions for better code documentation and type safety.
+
+## Rule Details
+
+This rule enforces that all functions have explicit return type annotations. Explicit return types serve as documentation, help catch bugs early, and make the codebase more maintainable.
+
+**Incorrect** code for this rule:
+
+```typescript
+function getName() {
+  return "John Doe";
+}
+
+const getAge = () => {
+  return 25;
+};
+
+function processUser() {
+  console.log("Processing user");
+}
+
+const calculateTotal = (items: Item[]) => {
+  return items.reduce((sum, item) => sum + item.price, 0);
+};
+
+async function fetchData() {
+  return await api.get("/data");
+}
+
+export function validateEmail(email: string) {
+  return email.includes("@");
+}
+```
+
+**Correct** code for this rule:
+
+```typescript
+function getName(): string {
+  return "John Doe";
+}
+
+const getAge = (): number => {
+  return 25;
+};
+
+function processUser(): void {
+  console.log("Processing user");
+}
+
+const calculateTotal = (items: Item[]): number => {
+  return items.reduce((sum, item) => sum + item.price, 0);
+};
+
+async function fetchData(): Promise<Data> {
+  return await api.get("/data");
+}
+
+export function validateEmail(email: string): boolean {
+  return email.includes("@");
+}
+```
+
+## Exceptions
+
+This rule does NOT require return types for:
+
+### Callback Functions
+
+```typescript
+// All of these are allowed without return types
+items.map((item) => item.name);
+items.filter((item) => item.active);
+items.forEach((item) => console.log(item));
+setTimeout(() => console.log("done"), 1000);
+promise.then((result) => result.data);
+```
+
+### Object Properties
+
+```typescript
+const handler = {
+  onClick: () => console.log("clicked"),
+};
+```
+
+### Array Elements
+
+```typescript
+const callbacks = [() => 1, () => 2];
+```
+
+### React Components (PascalCase)
+
+```typescript
+// React components don't need explicit return types
+const MyComponent = () => <div>Hello</div>;
+
+function UserProfile() {
+  return <div>User</div>;
+}
+
+const Button = () => {
+  return <button>Click</button>;
+};
+```
+
+## Benefits
+
+- **Self-documenting code**: Return types serve as documentation for function contracts
+- **Early error detection**: Type mismatches are caught at compile time
+- **Better IDE support**: Explicit types improve autocomplete and refactoring
+- **API clarity**: Public functions have clear type signatures
+- **Maintainability**: Easier to understand function behavior at a glance
+
+## When Not To Use
+
+- When you prefer TypeScript's type inference for all functions
+- In rapid prototyping where explicit types slow down development
+- When the inferred type is exactly what you want
+
+## Configuration
+
+This rule has no configuration options.
+
+## Related Rules
+
+- [@typescript-eslint/explicit-function-return-type](https://typescript-eslint.io/rules/explicit-function-return-type/) - Similar rule from typescript-eslint
+- [@typescript-eslint/explicit-module-boundary-types](https://typescript-eslint.io/rules/explicit-module-boundary-types/) - Requires explicit types on exported functions