DEV Community: Maxime Sahroui

The Boy Scout Rule: Leave Code Better Than You Found It

Maxime Sahroui — Fri, 20 Feb 2026 07:17:30 +0000

"Always leave the campground cleaner than you found it." — The Boy Scouts

Robert C. Martin adapted this principle for software: every time you touch a file, leave it a little better than you found it. Not a rewrite. Not a refactoring sprint. Just a small, deliberate improvement — on every commit, every PR, every day.

This is the most underrated practice in software engineering. It requires no planning, no tickets, no approval. It compounds silently until one day you realize the codebase doesn't hurt anymore.

Why It Works

Codebases don't rot overnight. They decay one shortcut at a time — a vague variable name here, a duplicated condition there, an unused import nobody cleaned up. Each one is trivial. Together, they make the code hostile to change.

The Boy Scout Rule reverses that entropy at the same rate it accumulates. You're not trying to fix everything. You're making sure the trend line points up instead of down.

The math is simple: if 5 engineers each make one micro-improvement per commit, and each pushes 3 commits a day, that's 75 improvements per week. In a quarter, you've made nearly a thousand small things better — without ever scheduling a "tech debt sprint."

What Counts as a Micro-Refactor

The key constraint: the improvement must not change behavior. If your PR is about adding a new endpoint, your Boy Scout cleanup should be invisible to the reviewer's eye — obvious, safe, and small.

Here's what qualifies:

Rename a vague variable

You're debugging a function and see d. You now know it's a duration in milliseconds. Rename it before you move on.

// before — what is d?
function isExpired(token: Token): boolean {
  const d = Date.now() - token.issuedAt;
  return d > 3600000;
}

// after — future you says thanks
const ONE_HOUR_MS = 3_600_000;

function isExpired(token: Token): boolean {
  const elapsed = Date.now() - token.issuedAt;
  return elapsed > ONE_HOUR_MS;
}

Three changes, zero risk: a meaningful name, an extracted constant, and a numeric separator for readability. The function does exactly the same thing.

Replace a magic string with a union type

You're adding a new case to a status check and notice the existing code uses raw strings everywhere. Lock it down.

// before — "active", "paused", "cancelled" scattered across the codebase
function canRenew(subscription: { status: string }): boolean {
  return subscription.status === "active" || subscription.status === "paused";
}

// after — the compiler catches typos for you
type SubscriptionStatus = "active" | "paused" | "cancelled";

type Subscription = {
  status: SubscriptionStatus;
  // ...other fields
};

function canRenew(subscription: Subscription): boolean {
  return subscription.status === "active" || subscription.status === "paused";
}

Now if someone writes "actve" anywhere, TypeScript catches it at compile time. You just eliminated an entire category of bugs in 30 seconds.

Extract a repeated condition into a named function

You notice the same check in two places while working on a feature. Don't copy-paste it a third time — extract it.

// before — this check appears in 3 different files
if (user.role === "admin" || user.role === "owner") {
  // ...
}

// after — one source of truth, readable everywhere
function hasElevatedAccess(user: User): boolean {
  return user.role === "admin" || user.role === "owner";
}

// now the call sites read like plain English
if (hasElevatedAccess(user)) {
  // ...
}

When the definition of "elevated access" changes — and it will — you change it in one place.

Clean up dead code

You're reading a module and spot an exported function that nothing imports. Check with a quick search and remove it.

# bun makes this fast — search the entire project in milliseconds
bun x grep-cli "calculateLegacyDiscount" src/
# no results? delete it.

Dead code is worse than no code. It misleads readers into thinking it matters, and it creates merge conflicts for no reason.

Add a return type

You're calling a function and have to read through the implementation to understand what it returns. Add the type so the next person doesn't have to.

// before — what does this return? you have to read every branch
function resolvePrice(item: CartItem, coupon?: Coupon) {
  if (!coupon) return item.basePrice;
  if (coupon.type === "percentage") return item.basePrice * (1 - coupon.value);
  return Math.max(0, item.basePrice - coupon.value);
}

// after — the contract is explicit
function resolvePrice(item: CartItem, coupon?: Coupon): number {
  if (!coupon) return item.basePrice;
  if (coupon.type === "percentage") return item.basePrice * (1 - coupon.value);
  return Math.max(0, item.basePrice - coupon.value);
}

One word added (: number). Now the function communicates its contract without requiring the reader to trace through three branches.

Replace an imperative loop with a declarative expression

You're reading through a data transformation and it takes you 30 seconds to understand a for loop that's really just a filter + map.

// before — imperative, you have to simulate the loop mentally
function getActiveEmails(users: User[]): string[] {
  const result: string[] = [];
  for (let i = 0; i < users.length; i++) {
    if (users[i].isActive && users[i].email) {
      result.push(users[i].email);
    }
  }
  return result;
}

// after — declarative, reads like a sentence
function getActiveEmails(users: User[]): string[] {
  return users
    .filter((user) => user.isActive && user.email)
    .map((user) => user.email);
}

Same output. But now the shape of the transformation — filter then project — is immediately visible.

The Rules of Engagement

The Boy Scout Rule only works if you respect its boundaries. Here's how to keep it safe and sustainable:

Keep it under 5 minutes. If a cleanup takes longer, it's not a Boy Scout improvement — it's a task. Write it down, create a ticket, and move on.

Never mix behavior changes with cleanups. Your PR should tell a clear story. Reviewers should be able to look at the diff and say "this part is the feature, this part is cleanup" — or better yet, put the cleanup in a separate commit.

Run the tests. Even a rename can break something if there's reflection, string-based lookups, or dynamic imports involved. With Bun, this takes seconds:

# run tests after every micro-refactor to make sure nothing broke
bun test

# or scope it to the files you touched
bun test src/pricing/

Don't refactor what you don't understand. If you're in unfamiliar code and you're not sure why something is written a certain way, don't touch it. The Boy Scout Rule is for improvements you're confident about — not for guessing.

Don't gold-plate. The goal is not to make every file perfect. It's to make it slightly better. Resist the urge to "while I'm here, let me also..." — that's how a 10-minute task becomes a 3-hour rabbit hole.

Making It a Team Habit

The Boy Scout Rule scales best when it's a shared norm, not a solo practice.

Name it in code reviews. When you see a small improvement in a PR, call it out positively: "Nice Boy Scout cleanup on the naming here." Reinforcement works better than mandates.

Lead by example. As a team lead, include a small cleanup in your own PRs. When people see it's normal and expected, they'll start doing it too.

Add it to your PR template. A simple checkbox — [ ] Boy Scout: left the code a little better — turns it from an abstract principle into a visible practice. It's a gentle nudge, not a gate.

Track it informally. You don't need metrics. But once a month, ask the team: "Does the codebase feel better or worse than last month?" If the answer is consistently "better" — the rule is working.

The AI-Powered Boy Scout

AI coding assistants are natural Boy Scouts — they can spot cleanup opportunities you'd miss when focused on your feature. The trick is to ask them explicitly and at the right moment.

Prompt your assistant before committing

Before you push, paste the diff or the files you touched and ask a focused question. Not "review my code" — that's too broad. Instead:

Here are the files I changed for the new billing endpoint.
Without changing any behavior, suggest small Boy Scout improvements:
renames, type tightening, dead code, extracted constants.
Only suggest changes you're confident are safe.

The constraint — "without changing behavior" and "confident are safe" — keeps the AI from going on a refactoring adventure. You get 2-3 surgical suggestions you can apply in a minute.

Add a Boy Scout pass to your AI rules

If you use project-level instructions (.claude/, .cursorrules, or a system prompt), you can make the Boy Scout Rule automatic:

# Boy Scout Rule

After completing any task, scan the files you touched for safe micro-refactors:
- Vague names that can be made specific
- Magic numbers or strings that should be named constants
- Missing return types on exported functions
- Unused imports or dead code
- Imperative loops that could be declarative
- Raw strings that should be union types

Apply these improvements in a SEPARATE commit with the message:
"chore: boy scout cleanup"

Constraints:
- Never change behavior. If unsure, skip it.
- Keep each cleanup under 5 lines changed.
- Do not refactor code you did not touch in this task.

This turns every AI-assisted task into a two-step process: ship the feature, then clean the campsite. The separate commit keeps the git history clean and makes review easy.

Use it in code review

When reviewing a PR (yours or someone else's), feed the diff to your AI assistant with a targeted prompt:

Review this PR diff. Ignore the feature logic — only flag Boy Scout
opportunities: naming, types, dead code, readability.
No behavior changes. Keep suggestions minimal and safe.

This is especially powerful for team leads reviewing junior developers' PRs. Instead of nitpicking names yourself, let the AI flag them — it feels less personal and more systematic.

A word of caution

AI assistants love to over-refactor. They'll suggest extracting a helper for a two-line function, or creating a generic utility for something used once. Remember Rule 4 of Simple Design: fewest elements. If the AI suggests an improvement that adds more complexity than it removes, skip it. The Boy Scout Rule is about making things simpler, not about maximizing the number of changes.

The Compound Effect

No single micro-refactor will transform your codebase. That's the point. You're not looking for a dramatic before-and-after. You're investing in a trend.

After a month, variable names are clearer. After a quarter, the module boundaries make more sense. After a year, new team members onboard faster because the code explains itself.

The Boy Scout Rule works because it removes the false choice between "shipping features" and "improving code quality." You do both, in every commit, forever.

Leave it better than you found it. Every time.

The 4 Rules of Simple Design: A Practical Guide with TypeScript

Maxime Sahroui — Fri, 13 Feb 2026 12:14:01 +0000

Kent Beck introduced the 4 Rules of Simple Design as part of Extreme Programming in the late 1990s. Decades later, they remain one of the most elegant and practical frameworks for writing maintainable software. These rules define what "simple" truly means in code — not naive or dumbed-down, but intentionally minimal.

The rules are ordered by priority. You never sacrifice a higher-priority rule to satisfy a lower one.

Rule 1: Passes the Tests

The code must work. It must do what it's supposed to do, and you must be able to prove it. A beautiful design that produces wrong results is worthless.

This rule also implies that tests exist. Untested code is not "simple" — it's unknown.

// ❌ No tests, no confidence
function calculateDiscount(price: number, tier: string): number {
  if (tier === "gold") return price * 0.8;
  if (tier === "silver") return price * 0.9;
  return price;
}

// ✅ Tested behavior — we know exactly what this does
describe("calculateDiscount", () => {
  it("applies 20% discount for gold tier", () => {
    expect(calculateDiscount(100, "gold")).toBe(80);
  });

  it("applies 10% discount for silver tier", () => {
    expect(calculateDiscount(100, "silver")).toBe(90);
  });

  it("applies no discount for unknown tiers", () => {
    expect(calculateDiscount(100, "bronze")).toBe(100);
  });
});

The key insight: tests are not overhead. They are the first rule. Everything else builds on the confidence they provide.

Rule 2: Reveals Intention

Code should clearly communicate what it does and why. A reader — including your future self — should understand the purpose without digging through implementation details.

// ❌ What does this do? You have to execute it mentally.
function process(items: { a: number; s: string; d: Date }[]) {
  return items.filter((i) => {
    const n = Date.now();
    const t = i.d.getTime();
    return n - t < 86400000 && i.a > 0 && i.s === "A";
  });
}

// ✅ The code reads like a specification
type OrderItem = {
  amount: number;
  status: "active" | "cancelled" | "pending";
  createdAt: Date;
};

const ONE_DAY_MS = 24 * 60 * 60 * 1000;

function isRecentActiveOrder(order: OrderItem): boolean {
  const age = Date.now() - order.createdAt.getTime();
  return age < ONE_DAY_MS && order.amount > 0 && order.status === "active";
}

function getRecentActiveOrders(orders: OrderItem[]): OrderItem[] {
  return orders.filter(isRecentActiveOrder);
}

Notice what changed: meaningful types, descriptive names, extracted constants, and a named predicate function. The behaviour is identical — but the intention is now unmistakable.

Naming: clarity is not verbosity

Revealing intention doesn't mean cramming every detail into a name. Over-descriptive names add cognitive load without adding clarity. If the name repeats context already obvious from the module, the type signature, or the surrounding code, it's noise — not intention.

// ❌ Too verbose — the names repeat context that's already clear
// file: userService.ts
function getUserByIdFromDatabaseAndReturnUserObject(userId: string): Promise<User> { ... }
function validateUserEmailAddressFormat(emailAddress: string): boolean { ... }
function checkIfUserAccountIsCurrentlyActive(user: User): boolean { ... }
function sendPasswordResetEmailNotificationToUser(user: User): Promise<void> { ... }

// ❌ Too vague — the names tell you nothing
function get(id: string): Promise<unknown> { ... }
function check(s: string): boolean { ... }
function do(u: unknown): Promise<void> { ... }

// ✅ Concise — context is already provided by the module and types
// file: users.ts
function findById(userId: string): Promise<User> { ... }
function isValidEmail(email: string): boolean { ... }
function isActive(user: User): boolean { ... }
function sendPasswordReset(user: User): Promise<void> { ... }

// The caller reads naturally:
import * as users from "./users";
const user = await users.findById(id);
if (users.isActive(user)) { ... }

The module name (users) already provides the domain context. The type signature (User, string) already tells you what goes in and what comes out. The function name only needs to express the action — everything else is redundant. Good naming lives in the sweet spot between cryptic and encyclopedic.

Rule 3: No Duplication (DRY)

Every piece of knowledge should live in exactly one place. Duplication isn't just repeated code — it's repeated concepts. When the same business rule appears in two places, you'll eventually change one and forget the other.

// ❌ The pricing logic is duplicated across two functions
// invoice.ts

type LineItem = {
  price: number;
  quantity: number;
};

function calculateSubtotal(items: LineItem[]): number {
  let total = 0;
  for (const item of items) {
    total += item.price * item.quantity;
    if (item.quantity >= 10) {
      total -= item.price * item.quantity * 0.1; // bulk discount
    }
  }
  return total;
}

function generatePreview(items: LineItem[]): string {
  let total = 0;
  for (const item of items) {
    total += item.price * item.quantity;
    if (item.quantity >= 10) {
      total -= item.price * item.quantity * 0.1; // bulk discount
    }
  }
  return `Estimated total: $${total.toFixed(2)}`;
}

// ✅ Single source of truth — each concept lives in one place
// pricing.ts

const BULK_THRESHOLD = 10;
const BULK_DISCOUNT_RATE = 0.1;

type LineItem = {
  price: number;
  quantity: number;
};

function lineItemSubtotal(item: LineItem): number {
  const gross = item.price * item.quantity;
  const discount = item.quantity >= BULK_THRESHOLD ? gross * BULK_DISCOUNT_RATE : 0;
  return gross - discount;
}

function calculateSubtotal(items: LineItem[]): number {
  return items.reduce((sum, item) => sum + lineItemSubtotal(item), 0);
}

// invoice.ts
function generatePreview(items: LineItem[]): string {
  return `Estimated total: $${calculateSubtotal(items).toFixed(2)}`;
}

The pricing logic now lives in lineItemSubtotal. Change the discount threshold once, and every consumer reflects it. No classes needed — just composable functions.

Rule 4: Fewest Elements

Once rules 1–3 are satisfied, use the minimum number of classes, functions, modules, and abstractions needed. Don't build for hypothetical futures. Don't add layers "just in case."

// ❌ Over-engineered for a simple need
type NotificationStrategy = {
  send(message: string, recipient: string): Promise<void>;
};

function createEmailStrategy(): NotificationStrategy {
  return {
    async send(message, recipient) {
      await sendEmail(recipient, message);
    },
  };
}

function createNotificationDispatcher(strategies: Record<string, NotificationStrategy>) {
  return async (type: string, message: string, recipient: string) => {
    const strategy = strategies[type];
    if (!strategy) throw new Error(`Unknown type: ${type}`);
    await strategy.send(message, recipient);
  };
}

const dispatch = createNotificationDispatcher({
  email: createEmailStrategy(),
});

// ✅ Just send the email. Add abstractions when you actually need them.
async function sendNotification(message: string, recipient: string): Promise<void> {
  await sendEmail(recipient, message);
}

The dispatcher, the strategy interface, and the factory function — none of them are needed when you only have one notification channel. If you add SMS later, then introduce the abstraction. Not before.

The Priority Matters

The ordering is everything. Here's how conflicts are resolved:

Don't remove duplication (Rule 3) if it makes the code harder to understand (Rule 2). Sometimes a little repetition is clearer than a clever abstraction.
Don't simplify elements (Rule 4) if it reintroduces duplication (Rule 3). An extracted helper function is worth having even if it adds a function to the module.
Never sacrifice correctness (Rule 1) for anything. A clean, readable, DRY codebase that produces wrong results is just a well-organised bug.

// Sometimes duplication is clearer than a forced abstraction
// This is OK — Rule 2 (clarity) beats Rule 3 (DRY)

function formatUserGreeting(user: User): string {
  return `Hello, ${user.firstName} ${user.lastName}!`;
}

function formatAdminGreeting(admin: Admin): string {
  return `Welcome back, ${admin.firstName} ${admin.lastName}. You have ${admin.pendingReviews} pending reviews.`;
}

// ❌ Don't force this into a shared function to eliminate duplication
// The "shared" part (name formatting) is trivial, and the contexts are different

Summary

Priority	Rule	Question to Ask
1	Passes the Tests	Does it work? Can I prove it?
2	Reveals Intention	Can someone else understand this without asking me?
3	No Duplication	Is every concept expressed in exactly one place?
4	Fewest Elements	Can I remove anything without breaking rules 1–3?

These four rules are not a checklist you apply once. They form a continuous loop—the heartbeat of refactoring. After every change: green tests → clarify intent → remove duplication → simplify.

Appendix: AI Coding Rules

The following rule set can be used as instructions for AI coding assistants (LLMs, copilots, agents) to enforce Kent Beck's 4 Rules of Simple Design. Copy and adapt them to your system prompt, project rules, or .cursorrules / .claude configuration.

# AI Coding Rules — 4 Rules of Simple Design

You follow Kent Beck's 4 Rules of Simple Design in the order of their priority.
When rules conflict, higher-priority rules always win.

## Rule 1: Passes the Tests (Highest Priority)

- Every function you write or modify MUST have corresponding tests.
- If modifying existing code, run existing tests first. Never break them.
- Write the test BEFORE or alongside the implementation, never as an afterthought.
- Tests must cover: expected behaviour, edge cases, and error paths.
- If you are unsure whether behaviour is correct, ask — do not guess.
- Never mark a task as complete if tests are failing.

## Rule 2: Reveals Intention

- Use descriptive, specific names for variables, functions, types, and modules.
  Bad: `data`, `process`, `handle`, `item`, `tmp`, `val`
  Good: `unpaidInvoices`, `calculateShippingCost`, `OrderStatus`
- But avoid over-descriptive names that repeat context already clear from
  the module, the type signature, or the surrounding code.
  Bad: `getUserByIdFromDatabaseAndReturnUserObject`, `checkIfUserIsActive`
  Good: `findById` (in a users module), `isActive` (takes a User)
- Extract magic numbers and strings into named constants.
- Use TypeScript types to document the shape of data. Prefer `type` over
  `interface` — use `interface` only when declaration merging is needed.
- Prefer named functions over inline lambdas for non-trivial logic.
- Each function should do one thing. If you need "and" to describe it, split it.
- Comments explain WHY, never WHAT. The code itself explains what.

## Rule 3: No Duplication

- Never copy-paste logic. Extract shared behaviour into a function, type, or module.
- Duplication includes: repeated business rules, repeated conditionals,
  repeated data transformations, and repeated structural patterns.
- When you spot duplication, refactor it — even if you didn't introduce it.
- BUT: do not force an abstraction when two pieces of code only look similar
  on the surface but represent different concepts (Rule 2 takes priority).

## Rule 4: Fewest Elements (Lowest Priority)

- Do not create abstractions for hypothetical future requirements.
- Do not introduce unnecessary abstractions, factories, strategies, or wrappers
  unless there is a concrete, current need.
- Prefer functions over classes when no state management is required.
- Prefer module-level functions with namespace imports (`import * as users`)
  over classes with methods. Use types for data shapes, functions for behaviour.
- Remove dead code, unused imports, and unnecessary parameters.
- If an abstraction makes the code harder to follow without reducing real
  duplication, remove it.
- One file with 3 clear functions is better than 3 files with 1 function each,
  unless the functions serve genuinely different domains.

## Conflict Resolution

When rules conflict, apply this priority:
1. Working, tested code (Rule 1) > everything.
2. Clarity (Rule 2) > DRY (Rule 3). A little repetition is OK if the
   alternative is an unclear abstraction.
3. DRY (Rule 3) > Minimalism (Rule 4). An extra function to eliminate
   duplication is justified.
4. Never add complexity to satisfy Rule 4. Minimalism means removing
   unnecessary things, not avoiding necessary ones.

## Refactoring Loop

After every change, mentally run this loop:
1. Are all tests green? → If not, fix.
2. Does the code clearly express intent? → If not, rename/restructure.
3. Is there duplication? → If yes, extract.
4. Can anything be removed without breaking rules 1-3? → If yes, remove.

Introducing StableError: A TypeScript Library for Consistent Error Tracking

Maxime Sahroui — Fri, 26 Sep 2025 10:43:09 +0000

How a simple library can revolutionize your error monitoring and debugging workflow

The Problem with Traditional Error Tracking

Picture this: You're debugging a production issue where users are reporting "User not found" errors. You check your error tracking dashboard and see hundreds of similar errors, but they all have different IDs:

Error ID: a1b2c3d4 - "User 123 not found"
Error ID: e5f6g7h8 - "User 456 not found"
Error ID: i9j0k1l2 - "User 789 not found"

Even though these are essentially the same error (a user lookup failure), your monitoring system treats them as completely different issues. This makes it nearly impossible to:

Group related errors for effective analysis
Track error frequency accurately
Identify patterns in your application failures
Prioritize fixes based on real impact

Enter StableError: The Solution

StableError is a TypeScript library that solves this exact problem by generating stable, consistent error IDs based on the semantic content of your errors, not their variable parts.

The Magic: Same Error = Same ID

import { createStableError } from 'stable-error';

// These all generate the SAME error ID
const error1 = createStableError('User 123 not found', { 
  category: 'validation',
  metadata: { field: 'email' }
});

const error2 = createStableError('User 456 not found', { 
  category: 'validation',
  metadata: { field: 'email' }
});

const error3 = createStableError('USER 789 NOT FOUND', { 
  category: 'validation',
  metadata: { field: 'email' }
});

console.log(error1.id === error2.id); // true
console.log(error1.id === error3.id); // true

How It Works: Intelligent Message Normalization

StableError uses sophisticated message normalization to ensure that semantically identical errors produce the same ID:

1. Number Normalization

// All of these become "user NUMBER not found"
"User 123 not found"
"User 456 not found" 
"User 999999 not found"

2. UUID Normalization

// All of these become "user UUID not found"
"User 550e8400-e29b-41d4-a716-446655440000 not found"
"User 6ba7b810-9dad-11d1-80b4-00c04fd430c8 not found"

3. Timestamp Normalization

// All of these become "error at TIMESTAMP"
"Error at 2023-01-01T10:00:00Z"
"Error at 2023-12-31T23:59:59Z"
"Error at 1672531200000" // Unix timestamp

4. Case and Whitespace Normalization

// All of these become "user not found"
"User not found"
"USER NOT FOUND"
"  user   not   found  "

Smart Metadata Filtering

Not all metadata should affect error ID generation. StableError only considers "stable" metadata keys that represent the error's semantic meaning:

Included in ID generation:

type, code, field, operation, service, component

Ignored (variable data):

userId, timestamp, sessionId, requestId

// These generate the SAME ID (userId and timestamp are ignored)
createStableError('Error', { 
  metadata: { 
    field: 'email', 
    userId: 123,           // Ignored
    timestamp: '2023-01-01' // Ignored
  }
});

createStableError('Error', { 
  metadata: { 
    field: 'email', 
    userId: 456,           // Ignored  
    timestamp: '2023-12-31' // Ignored
  }
});

Real-World Usage Examples

1. API Error Handling

import { createStableError } from 'stable-error';

async function getUserById(id: string) {
  try {
    const user = await database.findUser(id);
    if (!user) {
      throw createStableError('User not found', {
        category: 'validation',
        statusCode: 404,
        severity: 'medium',
        metadata: { 
          field: 'userId',
          operation: 'user_lookup'
        }
      });
    }
    return user;
  } catch (error) {
    // Convert any unexpected errors to stable errors
    if (error instanceof Error && !error.id) {
      throw createStableError(error, {
        category: 'database',
        severity: 'high',
        metadata: { operation: 'user_lookup' }
      });
    }
    throw error;
  }
}

2. Error Monitoring Integration

// With your favorite error tracking service
import { createStableError } from 'stable-error';

function trackError(error: Error, context: any) {
  const stableError = createStableError(error, {
    category: 'api',
    severity: 'high',
    metadata: {
      service: 'user-service',
      component: 'auth-middleware'
    }
  });

  // Send to your monitoring service
  errorTracker.captureException(stableError, {
    tags: {
      errorId: stableError.id,
      category: stableError.category,
      severity: stableError.severity
    },
    extra: stableError.metadata
  });
}

3. Error Aggregation Dashboard

// Group errors by stable ID for analytics
const errorGroups = errors.reduce((groups, error) => {
  const stableError = createStableError(error);
  const id = stableError.id;

  if (!groups[id]) {
    groups[id] = {
      id,
      message: stableError.message,
      category: stableError.category,
      count: 0,
      firstSeen: stableError.timestamp,
      lastSeen: stableError.timestamp,
      severity: stableError.severity
    };
  }

  groups[id].count++;
  groups[id].lastSeen = stableError.timestamp;

  return groups;
}, {});

Key Features

✅ Stable Error IDs

Same error message + category + metadata = Same ID
8-character hexadecimal IDs for easy reference

✅ Full TypeScript Support

Complete type safety with comprehensive interfaces
IntelliSense support for all options and methods

✅ Flexible Input

Works with string messages or existing Error objects
Preserves original stack traces when converting

✅ Rich Error Information

Category classification
Severity levels (low, medium, high, critical)
HTTP status codes
Timestamps
Custom metadata

✅ JSON Serialization

const error = createStableError('Test error', {
  category: 'validation',
  severity: 'high'
});

const json = error.toJSON();
// {
//   id: "a1b2c3d4",
//   message: "Test error", 
//   category: "validation",
//   severity: "high",
//   timestamp: "2023-01-01T10:00:00Z",
//   statusCode: 500,
//   metadata: {},
//   stack: "Error: Test error\n    at ..."
// }

Installation and Quick Start

npm install stable-error
# or
yarn add stable-error
# or  
bun add stable-error

import { createStableError } from 'stable-error';

// Create your first stable error
const error = createStableError('Something went wrong', {
  category: 'api',
  severity: 'high',
  metadata: { endpoint: '/users', method: 'GET' }
});

console.log(`Error ID: ${error.id}`); // Always the same for this error type

Browser and Runtime Support

Modern browsers (ES2018+)
Node.js 14+
TypeScript 4.5+
Bun (fully tested)

Conclusion

StableError transforms error tracking from a chaotic mess into an organized, actionable system. By generating consistent IDs for semantically identical errors, it enables:

Better error analytics - See which errors actually matter
Faster debugging - Group related issues together
Improved prioritization - Focus on high-frequency problems
Cleaner dashboards - No more noise from variable data

Whether you're building a small application or managing a large-scale system, StableError provides the foundation for effective error monitoring and debugging. Give it a try and see how it can revolutionize your error tracking workflow.

Ready to get started? Check out the GitHub repository for full documentation, examples, and the latest updates.

StableError is open source and available under the MIT license.