typescript-best-practices

TypeScript Best Practices

Use this skill as the default guidance for any .ts or .tsx change.

Keep this file practical. Record the repo's actual TypeScript standards here.

References

• For review or review-and-fix requests on a working tree, branch, commit, or commit range, read references/review-and-fix-changes.md and use it as the workflow while keeping this file as the review rubric.

Intent

• Provide a single baseline for how TypeScript should be written and refactored.
• Keep code strongly typed, easy to read, and easy to change.
• Reduce AI slop such as defensive cleanup, vague abstractions, duplicate transforms, and weak fallbacks.

Fast Path

• Validate untyped JSON with Zod at the boundary.
• Keep functions small and composable.
• Keep boundary shapes separate from internal domain shapes.
• Convert external data once, then keep internal code strict and simple.
• Do not normalize values unless there is a real boundary or product reason.
• Preserve original source values; add derived internal keys when needed.
• Use null for meaningful absence in stable domain data.
• Reserve undefined for optional inputs and raw boundary payload fields.
• Reuse existing helpers before adding new ones.
• For string, number, URL, array, dictionary, dedupe, filter, or similar foundational logic, search for an existing shared helper location in the repo first and add shared logic there instead of burying it in feature code.
• Extract shared invariants and boundary adapters; do not invent generic cleanup utilities.
• Run a quick duplicate-code smoke test with jscpd after refactors and before review.
• Do not add or expand code comments unless the user explicitly asks for comments in code.

Priority Order

1. Follow project-specific conventions first.
2. Make boundaries typed and explicit.
3. Reuse existing helpers and invariants before adding new abstractions.
4. Extract repeated boundary adapters or invariants once repetition is real.
5. Prefer clarity over cleverness.
6. Apply style preferences only after correctness, boundaries, and reuse are settled.

Core Rules

1. Validate and coerce untyped boundary data once, then keep domain types strict.

Bad:

type Issue = {
  id: string;
  attemptCount: number;
};

function parseIssue({ body }: { body: string }): Issue {
  return JSON.parse(body) as Issue;
}

Good:

import { z } from "zod";

const issueSchema = z.object({
  id: z.string().min(1),
  attemptCount: z.coerce.number().int().nonnegative(),
});

type Issue = z.infer<typeof issueSchema>;

function parseIssue({ body }: { body: string }): Issue {
  return issueSchema.parse(JSON.parse(body) as unknown);
}

2. Keep functions small and composable. Use a params object when a function takes multiple authored parameters.

• Prefer function name() declarations over const name = () => {} for authored functions.

Bad:

function buildWorkspaceLabel(issue: Issue, ownerName?: string): string {
  const normalizedState = issue.state.trim().toLowerCase();
  const normalizedOwner = ownerName ? ownerName.trim() : "unassigned";
  const slug = `${issue.identifier}-${normalizedState}-${normalizedOwner}`
    .replaceAll(/[^\w-]+/g, "-")
    .replaceAll(/-+/g, "-")
    .replace(/^-|-$/g, "");

  if (!slug) {
    return "workspace";
  }

  return slug;
}

Good:

function buildWorkspaceLabel(params: {
  issue: Issue;
  ownerName?: string;
}): string {
  const stateKey = buildStateKey(params.issue.state);
  const ownerKey = buildOwnerKey(params.ownerName);

  return buildWorkspaceSlug({
    identifier: params.issue.identifier,
    stateKey,
    ownerKey,
  });
}

function buildOwnerKey(ownerName?: string): string {
  return ownerName ?? "unassigned";
}

3. Put foundational string, number, URL, array, dictionary, dedupe, and filter logic in shared helpers.

Bad:

function listUniqueIssueIds(issues: Issue[]): string[] {
  return [...new Set(issues.map((issue) => issue.id))];
}

Good:

import { unique } from "../shared/collections";

function listUniqueIssueIds(issues: Issue[]): string[] {
  return unique(issues.map((issue) => issue.id));
}

If no shared helper exists yet, search for an existing shared helper location first. For purely foundational logic like strings, numbers, URLs, arrays, dictionaries, deduping, or filtering, add the reusable helper there instead of embedding it inside a feature module. Always look for utils/helpers/etc folders for these

4. Do not write code comments unless the user explicitly requests them.

• This includes line comments, block comments, JSDoc, TODOs, commented-out code, and directive comments.
• Existing comments, neighboring style, lint rules, and documentation do not count as explicit user instruction.
• Express intent with precise names, types, small functions, and clear structure.
• Preserve accurate existing comments. If a change makes one stale, remove it instead of rewriting it unless the user explicitly requested code comments.

5. Prefer explicit boundary errors over defensive defaults.

Bad:

function parseLimit(value?: string): number {
  return Number(value) || 0;
}

Good:

const limitSchema = z.coerce.number().int().nonnegative();

function parseLimit(value: string): number {
  return limitSchema.parse(value);
}

Refactoring Rules

• Before adding a new helper, search the repo for an existing helper, transform, or adapter that already solves the same problem.
• For foundational logic on strings, numbers, URLs, arrays, dictionaries, deduping, or filtering, search for shared helper files first and add that logic there before introducing a feature-local helper.
• If the same invariant, transform, or adapter appears in multiple places, prefer extracting it over adding another copy.
• Extract after real repetition, not because two snippets look vaguely similar.
• Shared helpers should have a clear domain purpose.
• Do not introduce broad sanitize*, normalize*, clean*, or format* utilities that mix unrelated concerns.
• If an abstraction only exists to generically "clean up" values, the real fix is usually at a typed boundary.
• When refactoring, preserve the strongest existing types. Do not widen types just to make the refactor easier.
• Prefer small boundary adapters and invariant helpers over abstract utility layers.

Duplicate-Code Smoke Test

Use jscpd as a quick duplicate-code smoke test after refactors and before review, like a typecheck. From the current repository root, run:

cd "$(git rev-parse --show-toplevel)"
bunx --yes jscpd --format typescript --pattern '**/*.ts' --gitignore \
  --min-lines 12 --min-tokens 120 \
  --max-lines 5000 --max-size 1mb --reporters console --exitCode 0 .

• Keep tests ignored at first because fixtures often create noise; add repo-appropriate ignores or scope the pattern to production code when needed.
• Lower --min-tokens to 60-80 when hunting smaller helper duplication.
• Use --reporters html,console when a browsable report would help.
• Pair clone detection with targeted rg for semantic duplicates: repeated function names, comments, payload fields, or error strings. Exact clone tools do not catch same logic with different spelling.

Code Comment Rules

• Do not add or expand code comments unless the user explicitly requests them.
• Treat JSDoc, TODOs, explanatory blocks, commented-out code, and directive comments as code comments under this rule.
• Do not infer permission from existing comments, neighboring style, lint rules, generated examples, or documentation.
• Preserve accurate existing comments. If changed code makes one stale, remove it instead of rewriting it unless the user explicitly requested code comments.
• Make the code self-explanatory through precise names, strong types, small helpers, and clear structure.

Workflow

1. Read this skill before making TypeScript changes.
2. For review or review-and-fix tasks, read references/review-and-fix-changes.md before scoping the work.
3. Follow project-specific conventions first when they conflict with generic guidance.
4. When data crosses into the system as JSON, define a Zod schema at that boundary.
5. When values are already trusted and typed, avoid unnecessary cleanup or coercion.
6. Keep functions small and composable.
7. For functions with multiple authored parameters, usually prefer fn(params: { ... }).
8. For functions with a single parameter, pass the value directly instead of wrapping it in a params object unless there is a strong local reason not to.
9. Do not add or expand code comments unless the user explicitly requested them.
10. If the change is purely about strings, numbers, URLs, arrays, dictionaries, deduping, filtering, or similar foundational types, search for an existing shared helper location in the repo first and add the shared logic there.
11. After a refactor, run a quick jscpd duplicate-code smoke test when the repo/tooling can support it.
12. If the code seems to require as, stop and look for a safer typing or validation approach first.
13. Before adding a new helper or abstraction, search the repo for an existing pattern you should reuse.
14. If similar logic exists in multiple modules, prefer extracting a shared invariant or boundary adapter over adding another copy.
15. Use subagents to inspect the codebase for existing helpers, repeated transforms, and refactor opportunities before introducing a new abstraction when subagents are available.
16. Use subagents for bounded multi-file refactors when the write scope is clear, but avoid broad reusable utilities unless the repetition is real.
17. If a proposed abstraction only exists to generically "clean up" values, stop and check whether the real fix belongs at a typed boundary instead.

Red Flags

• JSON.parse(...) as Foo
• Number(value) || 0
• input.trim().toLowerCase() with no product reason
• repeated foo ?? default across business logic
• generic sanitize* or normalize* helpers with vague scope
• large feature-local helpers that should be split into small composable functions
• new feature-local string, number, URL, array, or dictionary helpers that should live in a shared helper file
• duplicated boundary transforms across multiple files
• domain types carrying both null and undefined without a good reason
• broad interfaces or classes passed through layers that only need one or two methods
• newly added or expanded code comments without an explicit user request
• stale existing comments left behind after the code they describe changes

Review Checklist

• Is raw JSON being validated with Zod instead of cast?
• Are functions small and composable?
• Is boundary parsing happening once and early?
• Are boundary DTOs or view shapes translated once into internal domain types?
• Is external payload variance handled at the boundary rather than leaking into internal logic?
• Is the code using null and undefined deliberately instead of mixing both through domain code?
• Is the code normalizing values without a clear boundary or product reason?
• If normalization is required, does the code preserve the original value and add a derived key?
• Is there already an existing helper, transform, or adapter in the repo that should be reused?
• For foundational string, number, URL, array, dictionary, dedupe, or filter logic, did the code search for and use a shared helper file instead of adding feature-local duplication?
• Should repeated invariants or boundary adapters be extracted instead of copied again?
• Did a jscpd smoke test or targeted rg search identify duplicate code worth refactoring?
• Is as being used where stronger checks or better types should exist instead?
• Are domain invariants modeled with exact types like unions, Map, Set, or as const values?
• Does the code depend on the smallest capability surface it needs?
• Did the change avoid adding or expanding code comments unless the user explicitly requested them?
• Were stale existing comments removed instead of rewritten when comments were not requested?
• Is the code hiding broken assumptions behind weak defaults or silent fallbacks?