js-codestyle

name	js-codestyle
description	Правила написания и ревью JavaScript и TypeScript-кода в лаконичном прагматичном стиле.

JS Codestyle

Используй этот skill, когда нужно писать, править или ревьюить JavaScript/TypeScript-код по локальным правилам стиля.

Правила применения

• Если в репозитории уже есть более сильная норма через линтер, форматтер или явные инструкции — она важнее общего гайда.
• Используй гайд как источник решений по стилю, а не как повод переписывать весь соседний код без запроса.
• Если стиль проекта расходится с гайдом точечно, предпочитай консистентность проекта.
• Следи не только за синтаксисом, но и за философией: лаконичность, отсутствие дублирования, прагматизм, производительность.

Ресурсы

• eslint.config.js — образцовый ESLint flat-конфиг, отражающий правила этого скилла (2 пробела, single quotes, без ;, one-var: consecutive, набор unicorn, JS+TS). Используй его как стартовую точку для нового проекта или как источник для подсветки нарушений; при ревью можно сверяться с правилами оттуда.

Философия

• Лаконичность — избегать избыточных переменных и функций, используемых один раз
• Без дублирования — код, повторяющийся 2+ раза, генерализовать или выносить в функции
• Производительность — эффективные алгоритмы и структуры данных
• Прагматизм — выбирать подход в зависимости от задачи
• Привычка > сложность — лаконичный код предпочтительнее

Стиль кодирования

Форматирование

• Отступы: 2 пробела
• Точки с запятой: никогда
• Кавычки: одинарные
• Длина строки: ~120 символов (не строго)

Декларация переменных

Минимализм: одно ключевое слово const/let для множественных деклараций через запятую

// ✅ Правильно — одно const
const userName = user?.profile?.name ?? 'Аноним',
  updatedUser = { ...user, lastLogin: Date.now() },
  { id, ...userData } = user,
  greeting = `Привет, ${userName}!`

// ❌ Неправильно — множественные const
const userName = user?.profile?.name ?? 'Аноним'
const updatedUser = { ...user, lastLogin: Date.now() }
const { id, ...userData } = user
const greeting = `Привет, ${userName}!`

Условия

Минимализм: использовать логические операторы вместо if для простых условий

// ✅ Правильно — лаконичные условия
cond && action()
!cond && action()
hasAccess || redirectToLogin()

// ❌ Неправильно — избыточный if
if(cond) action()
if(!cond) action()
if(!hasAccess) redirectToLogin()

// ✅ Сложные условия — if допустим
if(user.isActive && user.isPremium && hasAccess) {
  grantFullAccess()
  logEvent('premium_access')
  notifyAdmin()
}

// ✅ Цепочки условий
isValid && save() || showError()

Именование

• Переменные, функции: camelCase
• Классы, типы: PascalCase
• Константы: camelCase (не UPPER_CASE)
• Короткие функции: однобуквенные имена допустимы (x, i)
• Средние функции: сокращения допустимы (ctx, arr, idx)
• Без префиксов типов (strName, arrUsers)

Комментарии

• Язык: русский
• JSDoc для публичных API и сложных функций
• Простые функции без комментариев

// ✅ Сложная функция
/**
 * Обрабатывает данные с фильтрацией и сортировкой
 * @param {Array} users - Массив пользователей
 * @param {Object} options - Опции обработки
 * @param {Function} options.filter - Функция фильтрации
 * @param {Function} options.sort - Функция сортировки
 * @returns {Array} Обработанный массив пользователей
 */
function processUsers(users, { filter, sort }) {
  return users.filter(filter).sort(sort)
}

// ✅ Простая функция без комментариев
function sum(a, b) {
  return a + b
}

Архитектура

Парадигма

• Функциональный подход по умолчанию
• ООП/классы для сложных предметных областей
• Мутации допустимы для оптимизации
• Иммутабельность когда это имеет смысл

// ✅ Функциональный для простых задач
const doubleNumbers = nums => nums.map(n => n * 2)

// ✅ Класс для сложной предметной области
class OrderProcessingPipeline {
  constructor(config) {
    this.validators = config.validators
    this.processors = config.processors
  }

  process(order) {
    // сложная логика обработки
  }
}

// ✅ Мутация для производительности
function updateCache(cache, key, value) {
  cache[key] = value
  return cache
}

Функции

• Разумное количество параметров (обычно до 3-4, но не строго)
• Деструктуризация активно
• Default параметры использовать
• Стрелочные функции для коротких инлайновых колбэков
• Function declarations для сложных именованных функций

// ✅ Деструктуризация + defaults
function createUser({ name, email, role = 'user' }) {
  return { name, email, role, createdAt: Date.now() }
}

// ✅ Стрелочные для колбэков
const activeUsers = users.filter(u => u.isActive)

// ✅ Declaration для сложной логики
function processPayment(order, paymentMethod) {
  validateOrder(order)
  calculateTotal(order)
  chargePayment(paymentMethod)
}

Обработка ошибок

• Синхронно: предпочтительно try/catch
• Асинхронно: .catch() или возвращаемые Error объекты
• Promise chains: использовать .catch() для обработки
• Кастомные классы ошибок при необходимости

// ✅ Синхронная обработка
function parseJSON(str) {
  try {
    return JSON.parse(str)
  } catch (err) {
    console.error('Ошибка парсинга:', err)
    return null
  }
}

// ✅ Асинхронная обработка
function fetchData(url) {
  return fetch(url)
    .then(res => res.json())
    .catch(err => {
      console.error('Ошибка загрузки:', err)
      return null
    })
}

// ✅ Кастомная ошибка
class ValidationError extends Error {
  constructor(message, field) {
    super(message)
    this.name = 'ValidationError'
    this.field = field
  }
}

Современный JavaScript (ES6+)

Активно использовать:

• async/await и Promise chains (по ситуации)
• Optional chaining (?.)
• Nullish coalescing (??)
• Spread/rest (...)
• Destructuring
• Template literals
• Arrow functions

const userName = user?.profile?.name ?? 'Аноним',
  updatedUser = { ...user, lastLogin: Date.now() },
  { id, ...userData } = user,
  greeting = `Привет, ${userName}!`

Циклы и итерация

for..of — основной цикл для массивов, Map, Set и любых итерируемых объектов. for..in — не использовать (проблемы с прототипной цепочкой, нужен hasOwnProperty).

// ❌ Индексный цикл
for(let i = 0; i < items.length; i++) {
  process(items[i])
}

// ❌ while с инкрементом
let i = 0
while(item = items[i++]) {
  process(item)
}

// ✅ for..of
for(const item of items)
  process(item)

Итерация по объектам: Object.entries/Object.keys/Object.values + for..of вместо for..in + hasOwnProperty

// ❌ for..in + hasOwnProperty
for(const key in obj) {
  if(Object.hasOwn(obj, key)) {
    fn(obj[key], key)
  }
}

// ❌ for..in + hasOwnProperty (старый стиль)
const hasOwn = Object.prototype.hasOwnProperty
for(const key in obj) {
  if(hasOwn.call(obj, key)) {
    fn(obj[key], key)
  }
}

// ✅ Object.entries + for..of
for(const [key, val] of Object.entries(obj))
  fn(val, key)

// ✅ Object.keys / Object.values когда нужно что-то одно
for(const key of Object.keys(obj))
  fn(key)

for(const val of Object.values(obj))
  fn(val)

Map вместо объектов для внутренних хранилищ: убирает необходимость в hasOwnProperty полностью

// ❌ Объект как хранилище — нужен hasOwnProperty при итерации
const storage = {}
storage[id] = value
for(const key in storage) {
  if(Object.hasOwn(storage, key)) { ... }
}

// ✅ Map — нет проблем с прототипной цепочкой
const storage = new Map()
storage.set(id, value)
for(const [key, val] of storage)
  process(key, val)

Итерация по Map/Set:

// ✅ Map
for(const [key, val] of myMap)
  process(key, val)

// ✅ Set
for(const item of mySet)
  process(item)

Модули

• ESM (import/export)
• Порядок импортов:
  1. Стандартные модули Node.js
  2. Сторонние пакеты
  3. Собственные модули
• Default exports для простых модулей
• Named exports для модулей с несколькими экспортами

// ✅ Порядок импортов
import fs from 'fs'
import path from 'path'

import React from 'react'
import axios from 'axios'

import { processData } from './utils'
import { UserService } from './services'

Производительность

Выбор структур данных

Анти-паттерн: массив + фуллскан

Статические массивы для проверки вхождения/поиска — неэффективно. Используй Set/Map/RegExp.

// ❌ Массив + some/includes — O(n)
const errors = ['error', 'Error', 'failed'],
  hasError = str => errors.some(e => str.includes(e))

// ❌ Массив + includes — O(n)
const flags = ['--out', '--port']
flags.includes(flag) && processFlag(flag)

// ❌ Массив + find — O(n)
const configs = [{ key: 'prod', url: '...' }],
  config = configs.find(c => c.key === env)?.url

Правильно: Set/Map/RegExp — O(1) или лучше

// ✅ RegExp для поиска подстрок
const errorPattern = /error|Error|failed/,
  hasError = str => errorPattern.test(str)

// ✅ Set для вхождения — O(1)
const flags = new Set(['--out', '--port'])
flags.has(flag) && processFlag(flag)

// ✅ Map для маппинга — O(1)
const configs = new Map([
  ['prod', 'api.prod.com'],
  ['dev', 'api.dev.com']
]),
  config = configs.get(env)

// ✅ Object для простых маппингов
const configs = { prod: 'api.prod.com', dev: 'api.dev.com' },
  config = configs[env]

Алгоритмическая сложность

Избегать O(n²), использовать эффективные структуры данных

// ❌ O(n²)
function findDuplicates(arr) {
  return arr.filter((item, idx) => arr.indexOf(item) !== idx)
}

// ✅ O(n)
function findDuplicates(arr) {
  const seen = new Set()
  return arr.filter(item => {
    if (seen.has(item)) return true
    seen.add(item)
    return false
  })
}

// ❌ O(n²)
const removeDuplicates = arr => arr.filter((item, idx) => arr.indexOf(item) === idx)

// ✅ O(n)
const removeDuplicates = arr => [...new Set(arr)]

// ❌ Поиск в массиве — O(n)
const userIds = [1, 2, 3, 4, 5]
userIds.includes(targetId) && processUser(targetId)

// ✅ Поиск в Set — O(1)
const userIds = new Set([1, 2, 3, 4, 5])
userIds.has(targetId) && processUser(targetId)

Минимизация операций

// ❌ Копирование всех элементов
const updateItems = (items, id, data) =>
  items.map(item => item.id === id ? { ...item, ...data } : { ...item })

// ✅ Копирование только изменённого
const updateItems = (items, id, data) =>
  items.map(item => item.id === id ? { ...item, ...data } : item)

// ❌ Множественные проходы
function processData(items) {
  const filtered = items.filter(item => item.isActive),
    mapped = filtered.map(item => item.value),
    sorted = mapped.sort((a, b) => b - a)
  return sorted
}

// ✅ Один проход
const processData = items => items
  .reduce((acc, item) => {
    item.isActive && acc.push(item.value)
    return acc
  }, [])
  .sort((a, b) => b - a)

Борьба с дублированием

Правило: если код повторяется 2+ раза — устранить дублирование

Приоритет методов:

1. Генерализация — переструктурировать код для универсальности (цикл, map, конфигурация)
2. Вынос в функцию — если генерализация невозможна
3. Вынос в переменную — для повторяющихся значений

Генерализация: цикл вместо дублирования

// ❌ Дублирование
const rootSource = await pickSource(opts.slug)
rootSource === 'content' && (rootChildren = await loadContent(base, opts.slug, rootTree))

const source = await pickSource(slug)
source === 'content' && (chosen = await loadContent(base, slug, tree))

// ✅ Генерализация — массив + цикл
const sources = [
  { slug: opts.slug, tree: rootTree },
  { slug, tree }
]

const [rootChildren, chosen] = await Promise.all(sources.map(async ({ slug, tree }) => {
  const source = await pickSource(slug)
  return source === 'content' ? await loadContent(base, slug, tree) : tree
}))

Генерализация: объект конфигурации

// ❌ Похожие функции
async function pickSource(slug) {
  const recipePath = path.resolve(__dirname, 'practicum-choose-source.goose.yaml')
  !await fileExists(recipePath) && (return 'tree')
  const result = await runGoose(recipePath, slug)
  return parseResult(result, 'tree')
}

async function pageSlug(title) {
  const recipePath = path.resolve(__dirname, 'practicum-page-slug.goose.yaml'),
    fallback = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
  !await fileExists(recipePath) && (return fallback)
  const result = await runGoose(recipePath, title)
  return parseResult(result, fallback)
}

// ✅ Конфигурация
const recipes = {
  source: {
    file: 'practicum-choose-source.goose.yaml',
    fallback: () => 'tree'
  },
  slug: {
    file: 'practicum-page-slug.goose.yaml',
    fallback: title => title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
  }
}

async function runRecipe(type, input) {
  const { file, fallback } = recipes[type],
    recipePath = path.resolve(__dirname, file)

  !await fileExists(recipePath) && (return fallback(input))

  const result = await runGoose(recipePath, input)
  return parseResult(result, fallback(input))
}

Генерализация: Map обработчиков

// ❌ Повторяющиеся условия
const [flag, value] = arg.split('=')

flag === '--parallel' && value && (opts.parallel = Math.max(1, +value))
flag === '--out' && value && (opts.out = path.resolve(value))
flag === '--slug' && value && (opts.slug = value)
flag === '--clear-cache' && (opts.clear = true)

// ✅ Map обработчиков
const handlers = {
  '--parallel': v => ({ parallel: Math.max(1, +v) }),
  '--out': v => ({ out: path.resolve(v) }),
  '--slug': v => ({ slug: v }),
  '--clear-cache': () => ({ clear: true })
}

const [flag, value] = arg.split('='),
  handler = handlers[flag]

handler && (value || flag === '--clear-cache') && Object.assign(opts, handler(value))

Генерализация: массив данных + Promise.all

// ❌ Множественные вызовы
const rootTreeJson = jsonTree(rootChildren)
rootTreeJson
  ? await fs.writeFile(base + '.tree.json', rootTreeJson)
  : await fs.rm(base + '.tree.json', { force: true })

const chosenTreeJson = jsonTree(chosen)
chosenTreeJson
  ? await fs.writeFile(base.file + '.tree.json', chosenTreeJson)
  : await fs.rm(base.file + '.tree.json', { force: true })

// ✅ Массив + Promise.all
await Promise.all([
  { data: rootChildren, path: base + '.tree.json' },
  { data: chosen, path: base.file + '.tree.json' }
].map(async ({ data, path }) => {
  const json = jsonTree(data)
  return json
    ? fs.writeFile(path, json)
    : fs.rm(path, { force: true })
}))

Вынос в функцию

Когда генерализация невозможна или усложнит код

// ❌ Дублирование логики
const json1 = JSON.stringify(data1)
json1
  ? await fs.writeFile('1.json', json1)
  : await fs.rm('1.json', { force: true })

const json2 = JSON.stringify(data2)
json2
  ? await fs.writeFile('2.json', json2)
  : await fs.rm('2.json', { force: true })

// ✅ Функция
async function writeJsonOrDelete(path, data) {
  const json = JSON.stringify(data)
  return json
    ? fs.writeFile(path, json)
    : fs.rm(path, { force: true })
}

await writeJsonOrDelete('1.json', data1)
await writeJsonOrDelete('2.json', data2)

Паттерны и анти-паттерны

Избегать

• Дублирование кода (2+ повтора)
• Массив + some/includes для статических списков (используй Set/Map/RegExp)
• Объекты как хранилища (используй Map/Set)
• for..in (используй for..of + Object.entries/Object.keys/Object.values)
• hasOwnProperty в любой форме (следствие for..in и объектов-хранилищ)
• Индексные циклы for(let i = 0; ...) и while(item = arr[i++]) (используй for..of)
• Магические числа и строки
• Переменные, используемые один раз
• Неэффективные алгоритмы (O(n²) вместо O(n))
• Множественные const/let вместо одного через запятую
• if для простых условий вместо логических операторов

Допустимо

• Глобальные переменные при необходимости
• Nested callbacks в любом объёме
• Длинные функции при необходимости
• Мутации для производительности

// ❌ Избыточная переменная
function double(n) {
  const result = n * 2
  return result
}

// ✅ Лаконично
const double = n => n * 2

// ❌ Магическое число
user.age > 18 && grantAccess()

// ✅ Именованная константа
const ADULT_AGE = 18
user.age > ADULT_AGE && grantAccess()

// ❌ Множественные декларации
const a = 1
const b = 2
const c = 3

// ✅ Одна декларация
const a = 1, b = 2, c = 3

// ❌ Избыточный if
if(isActive) processUser()
if(!hasError) sendResponse()

// ✅ Логические операторы
isActive && processUser()
hasError || sendResponse()

Типизация и валидация

TypeScript

• Использование: для больших и сложных проектов
• Строгость: максимальная, избегать any
• JSDoc: альтернатива для небольших проектов

Валидация данных

• Runtime валидация: использовать библиотеки (Zod, Yup, Joi) при необходимости
• Входные параметры: рассчитывать на соблюдение контрактов
• Устойчивость: писать код, устойчивый к разным типам входных данных

// ✅ Устойчивый код
const getLength = arr => Array.isArray(arr) ? arr.length : 0

// ✅ С проверкой во время выполнения
import { z } from 'zod'

const UserSchema = z.object({
  name: z.string(),
  email: z.string().email(),
  age: z.number().min(0)
})

function createUser(data) {
  const validated = UserSchema.parse(data)
  return { ...validated, createdAt: Date.now() }
}

Фронтенд

DOM и события

• Vanilla JS или React по необходимости
• Event delegation предпочтительнее для производительности
• addEventListener вместо onclick

// ✅ Event delegation
document.querySelector('.list').addEventListener('click', e => {
  e.target.matches('.item') && handleItemClick(e.target)
})

React

• Только functional components
• Hooks использовать по правилам React (не вызывать условно, только на верхнем уровне)
• Context API для state management

// ✅ Functional component
function UserCard({ user }) {
  const [isExpanded, setIsExpanded] = useState(false)

  return (
    <div className="UserCard" onClick={() => setIsExpanded(!isExpanded)}>
      <div className="UserCard-Name">{user.name}</div>
      {isExpanded && <div className="UserCard-Details">{user.email}</div>}
    </div>
  )
}

// ✅ Custom hook
function useUserData(userId) {
  const [user, setUser] = useState(null)

  useEffect(() => {
    fetchUserData(userId).then(setUser)
  }, [userId])

  return user
}

CSS

• CSS in CSS (не CSS-in-JS)
• BEM naming в стиле React:
  • Формат: BlockName-ElemName_modName_modVal
  • Имена записываются латиницей
  • Блоки и элементы: с заглавной буквы, каждое слово с заглавной (PascalCase)
  • Модификаторы: со строчной буквы
  • Имя элемента отделяется от блока одним дефисом (-)
  • Разделители модификаторов: подчёркивание (_)

/* ✅ BEM naming стиль React */
.UserCard { }
.UserCard-Avatar { }
.UserCard-Name { }
.UserCard-Details { }
.UserCard_premium { }
.UserCard_size_large { }
.UserCard-Avatar_rounded { }

Тестирование

Подход

• Unit-тесты: писать осмысленно, особенно для AI-генерируемого кода с нетривиальной логикой
• Фреймворк: Node.js testing framework
• TDD vs тесты после: по ситуации, TDD не включать ритуально без явного запроса или понятного регрессионного риска
• Новый автотест должен защищать конкретный поведенческий инвариант или риск регрессии
• Не писать тесты на «возвращение старого API» без явной просьбы сохранить обратную совместимость
• Не закреплять хрупкие детали: точные строки, снапшоты, порядок, номера строк, внутренние имена и текст ошибок проверять только когда это публичный контракт

// ✅ Простой тест
import { test } from 'node:test'
import assert from 'node:assert'

test('getUserStatus возвращает правильный статус', () => {
  assert.equal(
    getUserStatus({ isActive: true, isPremium: true }),
    'premium-active'
  )
  assert.equal(
    getUserStatus({ isActive: true, isPremium: false }),
    'active'
  )
})

Code Review приоритеты

Критично:

• Дублирование кода — устранить
• Неэффективные структуры данных (массив вместо Set/Map/RegExp)
• Лаконичность (размер кода)
• Алгоритмическая сложность
• Производительность

Вопрос вкуса:

• «Сложность» и «читаемость» кода (зависит от привычки)

Примеры кода в идеальном стиле

// ✅ Лаконичность
const processUsers = (users, filter) => users.filter(filter)

// ✅ Условная логика с тернарными операторами
const getUserStatus = ({ isActive, isPremium }) =>
  isActive ? isPremium ? 'premium-active' : 'active' : 'inactive'

// ✅ Async операции
function fetchUserData(userId) {
  return fetch(`/api/users/${userId}`)
    .then(res => res.json())
    .catch(err => {
      console.error(err)
      return null
    })
}

// ✅ Эффективная проверка через RegExp
const errorPattern = /error|Error|failed/,
  isValid = result => !errorPattern.test(result)

// ✅ Генерализация через Promise.all
await Promise.all([
  { data: rootChildren, path: base + '.tree.json' },
  { data: chosen, path: base.file + '.tree.json' }
].map(async ({ data, path }) => {
  const json = jsonTree(data)
  return json ? fs.writeFile(path, json) : fs.rm(path, { force: true })
}))

// ✅ Композиция функций
const compose = (...fns) => x => fns.reduceRight((acc, fn) => fn(acc), x),
  addTax = price => price * 1.2,
  addShipping = price => price + 10,
  formatPrice = price => `${price.toFixed(2)} ₽`,
  calculateTotal = compose(formatPrice, addShipping, addTax)

// ✅ Лаконичные условия и декларации
const userName = user?.profile?.name ?? 'Аноним',
  isActive = user?.isActive ?? false,
  { id, email, ...rest } = user

isActive && processUser()
hasError || showSuccess()