Repository: sindresorhus/type-fest

Stars: 17067

CLAUDE.md Copy Chapter

type-fest

TypeScript utility types library. Pure type-level programming—no runtime code.

Read .github/contributing.md for complete guidelines.

Commands Copy Chapter

npm test         # MUST pass before committing (runs all below)
npm run test:tsc # TypeScript compiler
npm run test:tsd # Type tests (tsd)
npm run test:xo  # Linter

File Structure Copy Chapter

source/type-name.d.ts → Type definition (.d.ts REQUIRED)
test-d/type-name.ts   → Tests (tsd)
index.d.ts            → Export (MUST add, lint enforces)
readme.md             → API docs (add to category)
source/internal/      → Shared helpers (not exported)

Code Patterns Copy Chapter

// ✅ CORRECT
import type {IsNever} from './is-never.d.ts';  // Include .d.ts
export type MyType<Value extends string> = ... // Descriptive names (not T/U)
export {};                                      // REQUIRED at end
// ❌ WRONG
import type {IsNever} from './is-never';       // Missing .d.ts
export type MyType<T> = ...;                   // Single-letter
/
Creates a tuple type of specified length with elements of specified type.
Use-cases:
- Define fixed-length arrays with specific types
@example

@category Array
*/
export type TupleOf<Length extends number, Fill = unknown> = ...;
export {};

Type params: Value, Target, Item, Length, Element, Key (not T, U, V, K)
Docs: No * prefix. First line → readme. Include use-cases, examples, @category.

Testing Copy Chapter

ALWAYS test edge cases (any, never, unknown).

expectType<string>('' as MyType<'foo'>);           // Basic
expectType<any>('' as MyType<any>);                // any/never/unknown
expectNotAssignable<MyType<'foo'>>({wrong: true}); // Negative
expectError<MyType<number>>();                     // Should error

Study: source/tuple-of.d.ts, is-equal.d.ts, literal-union.d.ts, internal/*.d.ts

Workflow Copy Chapter

1. Research - Study source/ similar types + online research
2. Define - source/type-name.d.ts with docs
3. Test - test-d/type-name.ts with edge cases
4. Export - Add to index.d.ts + readme.md
5. Verify - npm test must pass
6. Commit - `Add TypeName type or TypeName: Fix description

Critical Rules Copy Chapter

1. Import paths MUST include .d.ts extension
2. Files MUST end with export {};
3. Types MUST be exported from index.d.ts
4. Type params MUST use descriptive names (not T/U)
5. MUST test any, never, unknown edge cases
6. First doc line MUST be concise (goes in readme)
7. Use realistic examples with //=> comments
8. Include @category tags
9. Fix lint issues, don't disable rules

Type Programming Copy Chapter

- Conditionals: T extends U ? X : Y
- Recursion: type Loop<T, Acc> = ... Loop<...> ...
- Extract: infer Item
- Distribute: T extends any ? ... : never
- Count via tuple ['length']
- Union distribution is tricky—test it

Philosophy Copy Chapter

- Correctness > cleverness
- Real problems only
- Docs teach how, not what
- Edge cases mandatory
- One concept per PR
- Descriptive names > brevity
- No unrelated changes

Troubleshooting Copy Chapter

- Tests fail? Check .d.ts imports, export {};, edge cases (any, never, unknown)
- Lint errors? Add to index.d.ts`, fix issues (don't disable rules)