agent-rules / rules

---
description: JavaScript performance micro-optimizations for React applications including loops, caching, data structures, Set/Map lookups, array methods, RegExp hoisting, and immutable operations. Use when optimizing hot paths, working with arrays, loops, caching, or data structure lookups.
globs: "*.tsx,*.jsx,*.ts,*.js"
alwaysApply: false
---

# JavaScript Performance

Micro-optimizations for hot paths that can add up to meaningful improvements.

## 1. Avoid Layout Thrashing

**Impact: MEDIUM** - Prevents forced synchronous layouts

Avoid interleaving style writes with layout reads. Reading layout properties between style changes forces synchronous reflow.

**This is OK: browser batches style changes**

```typescript
function updateElementStyles(element: HTMLElement) {
  element.style.width = '100px'
  element.style.height = '200px'
  element.style.backgroundColor = 'blue'
  element.style.border = '1px solid black'
}
```

**Incorrect: interleaved reads and writes force reflows**

```typescript
function layoutThrashing(element: HTMLElement) {
  element.style.width = '100px'
  const width = element.offsetWidth // Forces reflow
  element.style.height = '200px'
  const height = element.offsetHeight // Forces another reflow
}
```

**Correct: batch writes, then read once**

```typescript
function updateElementStyles(element: HTMLElement) {
  element.style.width = '100px'
  element.style.height = '200px'
  element.style.backgroundColor = 'blue'
  element.style.border = '1px solid black'

  // Read after all writes (single reflow)
  const { width, height } = element.getBoundingClientRect()
}
```

**Better: use CSS classes**

```tsx
// Incorrect: interleaving style changes with layout queries
function Box({ isHighlighted }: { isHighlighted: boolean }) {
  const ref = useRef<HTMLDivElement>(null)

  useEffect(() => {
    if (ref.current && isHighlighted) {
      ref.current.style.width = '100px'
      const width = ref.current.offsetWidth // Forces layout
      ref.current.style.height = '200px'
    }
  }, [isHighlighted])

  return <div ref={ref}>Content</div>
}

// Correct: toggle class
function Box({ isHighlighted }: { isHighlighted: boolean }) {
  return (
    <div className={isHighlighted ? 'highlighted-box' : 'box'}>
      Content
    </div>
  )
}
```

---

## 2. Build Index Maps for Repeated Lookups

**Impact: LOW-MEDIUM** - O(n) to O(1) per lookup

Multiple `.find()` calls by the same key should use a Map.

**Incorrect (O(n) per lookup):**

```typescript
function processOrders(orders: Order[], users: User[]) {
  return orders.map(order => ({
    ...order,
    user: users.find(u => u.id === order.userId)
  }))
}
```

**Correct (O(1) per lookup):**

```typescript
function processOrders(orders: Order[], users: User[]) {
  const userById = new Map(users.map(u => [u.id, u]))

  return orders.map(order => ({
    ...order,
    user: userById.get(order.userId)
  }))
}
```

For 1000 orders x 1000 users: 1M ops -> 2K ops.

---

## 3. Cache Property Access in Loops

**Impact: LOW-MEDIUM** - Reduces lookups

Cache object property lookups in hot paths.

**Incorrect: 3 lookups x N iterations**

```typescript
for (let i = 0; i < arr.length; i++) {
  process(obj.config.settings.value)
}
```

**Correct: 1 lookup total**

```typescript
const value = obj.config.settings.value
const len = arr.length
for (let i = 0; i < len; i++) {
  process(value)
}
```

---

## 4. Cache Repeated Function Calls

**Impact: MEDIUM** - Avoids redundant computation

Use a module-level Map to cache function results.

**Incorrect: redundant computation**

```typescript
function ProjectList({ projects }: { projects: Project[] }) {
  return (
    <ul>
      {projects.map(project => {
        // slugify() called 100+ times for same names
        const slug = slugify(project.name)
        return <li key={slug}>{project.name}</li>
      })}
    </ul>
  )
}
```

**Correct: cached results**

```typescript
const slugifyCache = new Map<string, string>()

function cachedSlugify(text: string): string {
  if (slugifyCache.has(text)) {
    return slugifyCache.get(text)!
  }
  const result = slugify(text)
  slugifyCache.set(text, result)
  return result
}

function ProjectList({ projects }: { projects: Project[] }) {
  return (
    <ul>
      {projects.map(project => {
        const slug = cachedSlugify(project.name)
        return <li key={slug}>{project.name}</li>
      })}
    </ul>
  )
}
```

Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.

---

## 5. Cache Storage API Calls

**Impact: LOW-MEDIUM** - Reduces expensive I/O

`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive.

**Incorrect: reads storage on every call**

```typescript
function getTheme() {
  return localStorage.getItem('theme') ?? 'light'
}
// Called 10 times = 10 storage reads
```

**Correct: Map cache**

```typescript
const storageCache = new Map<string, string | null>()

function getLocalStorage(key: string) {
  if (!storageCache.has(key)) {
    storageCache.set(key, localStorage.getItem(key))
  }
  return storageCache.get(key)
}

function setLocalStorage(key: string, value: string) {
  localStorage.setItem(key, value)
  storageCache.set(key, value)
}
```

**Invalidate on external changes:**

```typescript
window.addEventListener('storage', (e) => {
  if (e.key) storageCache.delete(e.key)
})

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'visible') {
    storageCache.clear()
  }
})
```

---

## 6. Combine Multiple Array Iterations

**Impact: LOW-MEDIUM** - Reduces iterations

Multiple `.filter()` or `.map()` calls iterate multiple times.

**Incorrect: 3 iterations**

```typescript
const admins = users.filter(u => u.isAdmin)
const testers = users.filter(u => u.isTester)
const inactive = users.filter(u => !u.isActive)
```

**Correct: 1 iteration**

```typescript
const admins: User[] = []
const testers: User[] = []
const inactive: User[] = []

for (const user of users) {
  if (user.isAdmin) admins.push(user)
  if (user.isTester) testers.push(user)
  if (!user.isActive) inactive.push(user)
}
```

---

## 7. Early Length Check for Array Comparisons

**Impact: MEDIUM-HIGH** - Avoids expensive operations when lengths differ

When comparing arrays, check lengths first.

**Incorrect: always runs expensive comparison**

```typescript
function hasChanges(current: string[], original: string[]) {
  return current.sort().join() !== original.sort().join()
}
```

**Correct: O(1) length check first**

```typescript
function hasChanges(current: string[], original: string[]) {
  if (current.length !== original.length) {
    return true
  }

  const currentSorted = current.toSorted()
  const originalSorted = original.toSorted()

  for (let i = 0; i < currentSorted.length; i++) {
    if (currentSorted[i] !== originalSorted[i]) {
      return true
    }
  }
  return false
}
```

---

## 8. Early Return from Functions

**Impact: LOW-MEDIUM** - Avoids unnecessary computation

Return early when result is determined.

**Incorrect: processes all items after finding answer**

```typescript
function validateUsers(users: User[]) {
  let hasError = false
  let errorMessage = ''

  for (const user of users) {
    if (!user.email) {
      hasError = true
      errorMessage = 'Email required'
    }
    if (!user.name) {
      hasError = true
      errorMessage = 'Name required'
    }
  }

  return hasError ? { valid: false, error: errorMessage } : { valid: true }
}
```

**Correct: returns immediately on first error**

```typescript
function validateUsers(users: User[]) {
  for (const user of users) {
    if (!user.email) {
      return { valid: false, error: 'Email required' }
    }
    if (!user.name) {
      return { valid: false, error: 'Name required' }
    }
  }

  return { valid: true }
}
```

---

## 9. Hoist RegExp Creation

**Impact: LOW-MEDIUM** - Avoids recreation

Don't create RegExp inside render.

**Incorrect: new RegExp every render**

```tsx
function Highlighter({ text, query }: Props) {
  const regex = new RegExp(`(${query})`, 'gi')
  const parts = text.split(regex)
  return <>{parts.map((part, i) => ...)}</>
}
```

**Correct: memoize or hoist**

```tsx
const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/

function Highlighter({ text, query }: Props) {
  const regex = useMemo(
    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
    [query]
  )
  const parts = text.split(regex)
  return <>{parts.map((part, i) => ...)}</>
}
```

**Warning: global regex has mutable state**

```typescript
const regex = /foo/g
regex.test('foo') // true, lastIndex = 3
regex.test('foo') // false, lastIndex = 0
```

---

## 10. Use Loop for Min/Max Instead of Sort

**Impact: LOW** - O(n) instead of O(n log n)

Finding min/max only requires a single pass.

**Incorrect (O(n log n)):**

```typescript
function getLatestProject(projects: Project[]) {
  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
  return sorted[0]
}
```

**Correct (O(n)):**

```typescript
function getLatestProject(projects: Project[]) {
  if (projects.length === 0) return null

  let latest = projects[0]

  for (let i = 1; i < projects.length; i++) {
    if (projects[i].updatedAt > latest.updatedAt) {
      latest = projects[i]
    }
  }

  return latest
}

function getOldestAndNewest(projects: Project[]) {
  if (projects.length === 0) return { oldest: null, newest: null }

  let oldest = projects[0]
  let newest = projects[0]

  for (let i = 1; i < projects.length; i++) {
    if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
    if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
  }

  return { oldest, newest }
}
```

---

## 11. Use Set/Map for O(1) Lookups

**Impact: LOW-MEDIUM** - O(n) to O(1)

Convert arrays to Set/Map for repeated membership checks.

**Incorrect (O(n) per check):**

```typescript
const allowedIds = ['a', 'b', 'c', ...]
items.filter(item => allowedIds.includes(item.id))
```

**Correct (O(1) per check):**

```typescript
const allowedIds = new Set(['a', 'b', 'c', ...])
items.filter(item => allowedIds.has(item.id))
```

---

## 12. Use toSorted() Instead of sort()

**Impact: MEDIUM-HIGH** - Prevents mutation bugs in React state

`.sort()` mutates the array in place. Use `.toSorted()` to create a new sorted array.

**Incorrect: mutates original array**

```typescript
function UserList({ users }: { users: User[] }) {
  const sorted = useMemo(
    () => users.sort((a, b) => a.name.localeCompare(b.name)),
    [users]
  )
  return <ul>{sorted.map(renderUser)}</ul>
}
```

**Correct: creates new array**

```typescript
function UserList({ users }: { users: User[] }) {
  const sorted = useMemo(
    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
    [users]
  )
  return <ul>{sorted.map(renderUser)}</ul>
}
```

**Fallback for older browsers:**

```typescript
const sorted = [...items].sort((a, b) => a.value - b.value)
```

**Other immutable array methods:**
- `.toSorted()` - immutable sort
- `.toReversed()` - immutable reverse
- `.toSpliced()` - immutable splice
- `.with()` - immutable element replacement

---

## Quick Reference

| Pattern | Impact | Symptom |
|---------|--------|---------|
| Avoid layout thrashing | MEDIUM | Interleaved reads/writes to DOM |
| Index maps | LOW-MEDIUM | Multiple .find() with same key |
| Cache property access | LOW-MEDIUM | Deep property access in loops |
| Cache function results | MEDIUM | Same function called repeatedly |
| Cache storage API | LOW-MEDIUM | Frequent localStorage reads |
| Combine iterations | LOW-MEDIUM | Multiple filter/map on same array |
| Early length check | MEDIUM-HIGH | Array comparisons |
| Early return | LOW-MEDIUM | Processing continues after result found |
| Hoist RegExp | LOW-MEDIUM | RegExp created in render |
| Loop for min/max | LOW | Sorting just to find extremes |
| Set/Map lookups | LOW-MEDIUM | Array.includes() in loops |
| toSorted() | MEDIUM-HIGH | sort() mutating React state |

More agent context in alonsarias/agent-rules

5 other files this repository gives its agents.