v2.0.0

This release introduces a comprehensive overhaul of the @fuzzy-street/errors library, focusing on performance, clarity, inheritance‑chain correctness, and improved ergonomics. Several internal mechanisms have been redesigned, and new capabilities have been added to support more robust error introspection.

---

✨ Key Enhancements

Improved Type Signatures & Context Handling

• Updated errorContexts type signatures for clarity and correctness.
• Refined comments and documentation for better developer understanding.
• Introduced getInheritedContextKeys() to lazily and accurately retrieve inherited context keys.
• Added buildMergedContext() improvements:
  • Correctly merges context from causes and parent errors.
  • Handles string causes, object causes, and parent context merging rules.
  • Avoids instantiating parent errors; merges keys directly for efficiency.

Constructor & Property Definition Optimizations

• Replaced large optional‑parameter constructor with a single options object.
• Reduced Object.defineProperty calls to one per property type.
• Improved performance by consolidating property definitions and using class‑level metadata.

Lazy Parent Chain Materialization

• Parent error instances are now created only when needed.
• followParentChain() and getErrorHierarchy() trigger materialization on demand.
• Results are cached to avoid repeated instantiation.
• More efficient inheritance chain traversal logic.

Context Retrieval Performance

• getContext() now uses a WeakMap for O(1) lookups.
• Fast path for direct access; slow path only when filtering parent context.
• Updated getErrorHierarchy() to use getOwnedContext() for accuracy.

Collision Detection Improvements

• Enhanced checkContextCollision() to detect:
  • Key collisions across parent/child contexts
  • Prototype property collisions
• More robust and predictable merging behavior.

Serialization & Stringification

• Improved toString() for cleaner, faster string construction.
• Refactored toJSON() to include all relevant properties for better logging/debugging.

Benchmarking Suite

• Added @fuzzy-street/benchmarks integration.
• Introduced comprehensive benchmark coverage:
  • Error creation
  • Context access
  • Serialization
  • Inheritance traversal
• Baseline reports added for:
  • v1.1.0
  • v2.0.0

---

📉 Performance & Memory Findings

v1.1.0 Baseline

• Native Error ~270–300% faster than custom errors.
• Custom error memory footprint ~400% larger.
• Direct property access ~31% faster than getContext().

v2 Baseline

• Error creation overhead reduced (native ~218–254% faster).
• Memory footprint significantly improved:
  • Simple custom error: +578%
  • Complex custom error: ~–9% (better than native in some cases)
• Direct property access still faster (~20%), but gap reduced.

---

🧨 Breaking Changes

1. Lazy Parent Chain Materialization

Before (v1.x):

error.parent // always exists immediately

Now (v2.0):

error.parent // undefined until materialized
QueryError.followParentChain(error) // materializes chain

If your code accessed error.parent directly, call followParentChain() first.

2. followParentChain() Return Value

• Now returns [] for errors without parents (instead of [error]).

3. toJSON() Field Naming

• Regression fixed; cause field preserved for backward compatibility.

---

📚 Migration Guide

If you use simple errors (no inheritance)

No changes required. You get:

• Faster creation
• Lower memory usage
• Same API surface

If you rely on inheritance

Use one of the following:

Option A — Materialize chain explicitly

const chain = QueryError.followParentChain(error);

Option B — Use class inheritance metadata

error.inheritanceChain.map(e => e.name);

If you previously walked .parent manually

Replace with:

const chain = ErrorClass.followParentChain(error);
chain.forEach(e => console.log(e.name));

---

🧹 Additional Cleanup

• Improved comments and formatting across internal methods.
• Added assertions to tests to ensure full inheritance chain correctness.
• Updated README to reflect new behavior and APIs.