@web-engine-dev/debug

Debug utilities including assertions, invariant checks, debug-only code blocks, and runtime diagnostics. All debug code is tree-shaken in production builds for zero overhead.

Layer 7 · Gameplay

Features

• Assertions: assert(), assertEqual(), assertDefined(), assertNever() with descriptive messages
• Invariants: invariant() for conditions that must always hold — throws with stack trace
• Debug Labels: Named debug scopes for grouping related assertions
• Conditional Blocks: DEBUG_ONLY(() => { ... }) blocks stripped in production
• Performance Marks: debugMark() and debugMeasure() for Performance API integration
• Type Guards: Runtime type checks that narrow TypeScript types
• Warning System: debugWarn() fires once per callsite (no spam)
• Tree-Shaking: All debug utilities resolve to no-ops via dead-code elimination in production
• Stack Traces: Clean stack traces with source map support

Installation

npm install @web-engine-dev/debug
# or
pnpm add @web-engine-dev/debug

Quick Start

import { assert, invariant, debugOnly, debugWarn } from '@web-engine-dev/debug';

// Assert — throws in development, removed in production
assert(entity !== null, 'Entity must exist');
assert(health > 0, `Health must be positive, got ${health}`);

// Invariant — for conditions that must always hold
invariant(array.length > 0, 'Array must not be empty');

// Debug-only code block — entire block removed in production
debugOnly(() => {
  validateEntityHierarchy(world);
  checkForOrphanedComponents(world);
});

// Warning that fires only once per callsite
debugWarn('Deprecated: use newMethod() instead'); // Logs once, silent on repeat calls

// Type narrowing assertions
function processEntity(entity: Entity | null) {
  assertDefined(entity, 'Expected entity');
  // TypeScript now knows: entity is Entity (not null)
  entity.update();
}

Production Behavior

In production builds (when process.env.NODE_ENV === 'production' or via build tool configuration):

Function	Production Behavior
assert()	Removed entirely (tree-shaken)
invariant()	Throws minimal error (no message string)
debugOnly()	Entire callback removed
debugWarn()	Removed entirely
debugMark()	Removed entirely

Dependencies

None — zero runtime dependencies.