@devlens/core

Stop wasting 30 minutes hunting silent failures. DevLens finds them for you -- automatically.

Your UI renders blank. No error in console. You add console.log everywhere until you discover user.profile.settings is undefined because the API silently returned a 500. Sound familiar?

DevLens detects these failures the moment they happen and tells you exactly what went wrong, where, and how to fix it.

What It Catches

Category	What It Detects	Example
Network	Failed API calls, 4xx/5xx responses, timeouts	`POST /api/users returned 500`
Null Access	Property access on null objects	`user.profile.avatar is null`
Undefined Data	Accessing undefined properties	`settings.theme is undefined`
Render Data	State values your UI depends on that are nullish	`"posts" is undefined in Dashboard`
Unhandled Errors	Uncaught exceptions and promise rejections	`TypeError: Cannot read property...`
Type Mismatch	Unexpected data types at runtime	`Expected string, got number`

Installation

npm install @devlens/core

Quick Start -- 4 Lines to Full Coverage

import {
  createDetectionEngine,
  createNetworkInterceptor,
  createGlobalCatcher,
  createDataGuardian,
} from '@devlens/core';

// 1. Create the engine
const engine = createDetectionEngine();

// 2. Auto-detect failed API calls (fetch + XHR)
const network = createNetworkInterceptor(engine);
network.install();

// 3. Catch uncaught errors + unhandled promise rejections
const catcher = createGlobalCatcher(engine);
catcher.install();

// 4. Detect null/undefined property access on any object
const guardian = createDataGuardian(engine);
const data = guardian.guard(apiResponse, 'apiResponse');

// Now this silently-failing access gets logged with full context:
console.log(data.user.profile.avatar);

What You See in Console

Instead of silence or a cryptic error, DevLens gives you:

[NET] DevLens [ERROR] network: POST /api/users returned 500 Internal Server Error
  |- Status: 500
  |- Duration: 1234ms
  |- Suggestion: Server returned 500 -- check server logs
  \- Source: NetworkInterceptor

[NULL] DevLens [WARN] null-access: Property "avatar" is null at path "user.profile.avatar"
  |- Path: user.profile.avatar
  |- Value: null
  |- Source: UserProfile
  \- Suggestion: Check if "avatar" is loaded/initialized before accessing

Every issue includes: what happened, where it happened, the actual value found, and a suggestion to fix it.

Configuration

const engine = createDetectionEngine({
  enabled: true,                // auto-disabled in production
  minSeverity: 'warn',         // 'error' | 'warn' | 'info'
  throttleMs: 1000,            // prevent log spam
  maxIssues: 100,              // memory buffer limit
  modules: {
    network: {
      fetch: true,              // intercept fetch()
      xhr: true,                // intercept XMLHttpRequest
      ignoreUrls: ['/health', /\.hot-update\./],
      logSuccess: false,        // only log failures
    },
    guardian: {
      maxDepth: 5,              // proxy depth limit
      ignorePaths: ['_internal'],
    },
    catcher: {
      windowErrors: true,       // window.onerror
      unhandledRejections: true, // unhandled promises
      consoleErrors: false,     // console.error interception
    },
  },
  ignore: {
    urls: ['/analytics'],
    messages: [/ResizeObserver/],
  },
});

API Reference

Functions

Export	Description
`createDetectionEngine(config?)`	Creates the core engine that coordinates all detection modules
`createNetworkInterceptor(engine, config?)`	Intercepts `fetch()` and `XMLHttpRequest` to detect API failures
`createDataGuardian(engine, config?)`	Wraps objects in ES6 Proxy to detect null/undefined property access
`createGlobalCatcher(engine, config?)`	Captures `window.onerror` and unhandled promise rejections
`createConsoleReporter()`	Formatted console output with severity colors and structured details

Types

Export	Description
`DetectedIssue`	Full issue object with id, severity, category, message, path, suggestion, stack
`DevLensConfig`	Engine configuration
`DevLensEngine`	Engine instance interface (report, subscribe, getIssues, isEnabled)
`Reporter`	Custom reporter interface -- implement to send issues anywhere
`Severity`	`'error' \| 'warn' \| 'info'`
`IssueCategory`	`'network' \| 'null-access' \| 'undefined-data' \| 'render-data' \| ...`
`NetworkInterceptorConfig`	Network module config
`DataGuardianConfig`	Guardian module config
`GlobalCatcherConfig`	Catcher module config

Custom Reporter

Send issues to your own logging service:

import type { Reporter, DetectedIssue } from '@devlens/core';

const myReporter: Reporter = {
  report(issue: DetectedIssue) {
    fetch('/api/logs', {
      method: 'POST',
      body: JSON.stringify(issue),
    });
  },
};

const engine = createDetectionEngine({ reporter: myReporter });

Framework Adapters

Package	Framework	What It Adds
@devlens/react	React 17+	Provider, ErrorBoundary, guarded hooks
@devlens/vue	Vue 3.3+	Plugin, auto error/warn handlers, guarded composables
@devlens/ui	Any	Visual debug panel overlay

Why @devlens/core

Zero dependencies -- nothing to audit, nothing to break
~20KB ESM bundle, tree-shakeable
Dual ESM + CJS output with full TypeScript declarations
Production-safe -- auto-disabled when NODE_ENV === 'production', zero overhead
Framework-agnostic -- works with React, Vue, Svelte, vanilla JS, anything
Pluggable -- custom reporters, custom validators, ignore patterns
Non-invasive -- no global state pollution, clean install/uninstall lifecycle

Roadmap

Version	Feature	Status
v2.0	Detection engine with network interceptor, data guardian, global catcher, console reporter	Current
v3.0	AI-powered analysis -- integrate Claude and Gemini models to analyze detected issues, identify root-cause patterns across your issue history, and generate actionable fix suggestions	Planned

The v3.0 AI integration will analyze patterns across your detected issues, identify root causes, and suggest fixes -- directly in your dev console or UI panel.

License

MIT -- GitHub -- Changelog