CLAUDE.md · toss/es-toolkit

Sections

1. Language
2. Quick Reference
3. Structure
4. Design Principles
5. Coding Conventions
6. New Function Checklist

First lines (shown under the repo's MIT license)

# CLAUDE.md

Instructions for AI assistants working on es-toolkit.

## Language

This is a global project with users speaking various languages. When producing non-code output (explanations, reviews, reports), respond in the user's preferred language.

## Quick Reference

```bash
corepack enable && yarn install   # Setup
yarn vitest run                   # Tests
yarn vitest run src/array/chunk   # Test specific function
yarn lint                         # ESLint
tsc --noEmit                      # Typecheck
```

## Structure

```
src/{category}/{fn}.ts            # Implementation (array, bigint, function, math, object, predicate, promise, set, string, util, error, map)
src/{category}/{fn}.spec.ts       # Tests (vitest)
src/compat/{category}/{fn}.ts     # Lodash-compatible variant
tests/types/compat.spec-d.ts      # Type tests against @types/lodash (yarn workspace type-tests test)
docs/reference/{category}/{fn}.md           # English
docs/ko/reference/{category}/{fn}.md        # Korean
docs/ja/reference/{category}/{fn}.md        # Japanese
docs/zh_hans/reference/{category}/{fn}.md   # Chinese
```

## Design Principles

- **Performance**: Must match or beat lodash.
- **Simplicity**: Simplest interface for the 85% use case. No complex options.
- **Don't implement**: Functions replaceable by modern JS (`Array.isArray`, `Number.isNaN`, `Math.min`), or TC39 Stage 3+ proposals.
- **es-toolkit vs compat**: `es-toolkit` is the strict, opinionated API. `es-toolkit/compat` matches lodash behavior exactly for migration. Compat is feature-complete — no new functions are being added. Only behavior inconsistency fixes against lodash are accepted.
- **compat runs on Node.js 6**: `es-toolkit/compat` is published for Node.js 6+ (no transpilation or polyfills needed by users), so `src/compat/**` is limited to ES2015 built-ins and ES2015 syntax, plus `?.` and `??`, which the build lowers (enforced by ESLint). Do not change main-library files for compat: if a main-library file compat imports needs a newer built-in, add an ES2015 copy under `src/compat` instead. The `compat-node6` CI job runs the built package on a real Node.js 6.
- **What we accept**: New functions need an accepted [discussion](https://github.com/toss/es-toolkit/discussions/new?category=ideas) first, performance work needs benchmark results, and refactoring-only changes are not accepted. See [`.github/CONTRIBUTING.md`](./.github/CONTRIBUTING.md#41-what-we-accept).

## Coding Conventions

- `for` loops over `reduce` (local mutation is fine)
- Built-in JS over custom helpers (`Array.isArray()`, not `isArray()`)
- Type params: `T` elements, `K` keys, `E` errors
- `readonly T[]` for array params that aren't mutated
- Detailed JSDoc with `@template`, `@param`, `@returns`, `@throws`, `@example`

## New Function Checklist

1. `src/{category}/{fn}.ts` — Implementation
2. `src/{category}/{fn}.spec.ts` — Tests
3. Re-export in `src/{category}/index.ts` and `src/index.ts`
4. Docs in all 4 languages (see `docs/CLAUDE.md` for templates)