amount); this.logAudit("REFUND"); }

private logAudit(action: string): void { console.log([${action}] ${this.id} | ${this.amount} ${this.currency}); } }

// Safe instantiation wrapper function createTransaction(config: TransactionConfig): TransactionProcessor { // Guard against missing new keyword if (!(this instanceof TransactionProcessor)) { return new TransactionProcessor(config); } return new TransactionProcessor(config); }

// Usage const tx1 = createTransaction({ id: "TX-001", amount: 150.00, currency: "usd" }); const tx2 = createTransaction({ id: "TX-002", amount: 75.50, currency: "eur" });

tx1.process(); tx2.process();

console.log(tx1.process === tx2.process); // true (shared reference) console.log(tx1 instanceof TransactionProcessor); // true

### Architecture Decisions & Rationale

1. **Prototype Delegation over Inline Methods:** Methods are defined on the class prototype (which compiles to `TransactionProcessor.prototype`). This ensures a single function reference per method, regardless of instance count. V8 can optimize these calls using inline caching.
2. **Safe Instantiation Guard:** The `createTransaction` wrapper checks `this instanceof TransactionProcessor`. If a developer accidentally calls `createTransaction()` without `new`, `this` defaults to the global object (or `undefined` in strict mode). The guard intercepts this and forces proper instantiation.
3. **Immutable Identifiers:** `id` is marked `readonly` to prevent accidental mutation after allocation. Transaction IDs should never change post-creation.
4. **Explicit State Initialization:** `processedAt` starts as `null` rather than `undefined`. This creates a consistent hidden class shape from allocation, preventing V8 from dropping to dictionary mode during state transitions.

## Pitfall Guide

### 1. Omitting the `new` Operator
**Explanation:** Calling a constructor without `new` binds `this` to the global object (or `undefined` in strict mode). Properties leak into the global scope or throw a `TypeError`.
**Fix:** Use strict mode (`"use strict"`) and implement a safe instantiation guard that checks `this instanceof Constructor` and recursively calls with `new`.

### 2. Defining Behavior Inside the Constructor
**Explanation:** Assigning functions directly to `this.methodName` creates a new function reference per instance. Memory scales linearly with instance count, and V8 cannot optimize property access.
**Fix:** Move all behavior to the prototype or class definition. Keep constructors strictly for state initialization.

### 3. Overwriting the Prototype Chain
**Explanation:** Reassigning `Constructor.prototype = { ... }` after instances are created breaks the `[[Prototype]]` link for existing objects. New instances will use the new prototype, but old ones retain the old chain.
**Fix:** Extend the prototype using `Object.assign(Constructor.prototype, { ... })` or define methods before instantiation. Never replace the prototype object after instances exist.

### 4. Returning Primitives from Constructors
**Explanation:** If a constructor returns a primitive (string, number, boolean, null, undefined), JavaScript ignores the return value and still returns the newly created `this` object. This creates silent logical bugs.
**Fix:** Only return objects from constructors. If you need factory behavior that returns primitives or different types, use a standalone factory function instead of a constructor.

### 5. Cross-Realm `instanceof` Failures
**Explanation:** `instanceof` checks the prototype chain against a specific constructor reference. In micro-frontends, iframes, or Web Workers, each realm has its own global context. An object created in one realm will fail `instanceof` checks in another, even if the class names match.
**Fix:** Use duck typing (`"process" in obj && typeof obj.process === "function"`) or implement a type guard with a static `TYPE` symbol. Avoid strict `instanceof` checks across realm boundaries.

### 6. Mutating Shared Prototype State
**Explanation:** Adding mutable objects (arrays, plain objects) directly to the prototype causes all instances to share the same reference. Modifying it in one instance corrupts state across the entire class.
**Fix:** Initialize mutable state inside the constructor. Only place immutable data or functions on the prototype.

### 7. Forgetting `this` Binding in Event Handlers
**Explanation:** Passing a prototype method directly to an event listener or callback loses its `this` context. The method executes with `this` as `undefined` or the event target.
**Fix:** Bind methods in the constructor, use arrow functions for callbacks, or leverage `Function.prototype.bind` at the call site.

## Production Bundle

### Action Checklist
- [ ] Verify strict mode is enabled to prevent global `this` leakage
- [ ] Audit constructors for inline method definitions and migrate to prototype delegation
- [ ] Implement safe instantiation guards for public-facing factory functions
- [ ] Ensure mutable state (arrays, objects) is initialized in the constructor, not the prototype
- [ ] Replace cross-realm `instanceof` checks with structural type guards or symbol-based identification
- [ ] Profile heap memory after instantiation spikes to confirm hidden class consistency
- [ ] Document constructor expectations using JSDoc or TypeScript interfaces for IDE autocompletion

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| High-frequency entity creation (>1k/sec) | Prototype-delegated class | Minimizes GC pressure, enables V8 inline caching | Low memory, high throughput |
| Cross-iframe/micro-frontend communication | Structural type guard | Avoids realm-bound `instanceof` failures | Negligible CPU, high reliability |
| Simple data transfer objects (DTOs) | Plain object literals or `Object.freeze()` | No behavior needed, zero allocation overhead | Lowest memory, fastest instantiation |
| Complex initialization with validation | Factory function with constructor fallback | Centralizes validation, prevents partial state | Slight CPU overhead, higher safety |
| Legacy codebase migration | Incremental prototype extraction | Reduces risk, allows gradual V8 optimization | Medium refactoring cost, long-term savings |

### Configuration Template

```typescript
// safe-instantiation.ts
export function createSafeInstance<T extends new (...args: any[]) => any>(
  Constructor: T,
  ...args: ConstructorParameters<T>
): InstanceType<T> {
  const instance = new Constructor(...args);
  
  // Runtime validation hook (optional)
  if (typeof instance.validate === "function") {
    instance.validate();
  }
  
  return instance;
}

// domain-entity.ts
export class DomainEntity {
  public readonly createdAt: number;
  public readonly version: number;

  constructor(id: string) {
    this.createdAt = Date.now();
    this.version = 1;
    this.id = id;
  }

  public validate(): void {
    if (!this.id || typeof this.id !== "string") {
      throw new TypeError("Entity ID must be a non-empty string");
    }
  }
}

// Usage
const entity = createSafeInstance(DomainEntity, "ENT-8842");

Quick Start Guide

1. Define the Interface: Create a TypeScript interface or JSDoc typedef describing the expected constructor arguments and instance shape.
2. Build the Constructor: Implement a class or function that assigns state to this. Avoid defining methods here.
3. Attach Shared Behavior: Add methods to the prototype or class definition. Ensure they reference this safely.
4. Wrap with Safe Instantiation: Create a factory function that checks this instanceof and delegates to new.
5. Validate in Production: Run a heap snapshot after bulk instantiation. Confirm method references are identical across instances (instanceA.method === instanceB.method).