error-less 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# error-less
+
+> Beautiful, Rust-style error reporting for Node.js
+
+[![npm version](https://img.shields.io/npm/v/error-less.svg)](https://www.npmjs.com/package/error-less)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Transform noisy Node.js stack traces into beautiful, actionable error reports with source code context—just like Rust, Next.js, and other modern frameworks.
+
+## Features
+
+- **Zero Configuration**: Just import and errors become beautiful
+- **Source Code Context**: See the exact line that caused the error with surrounding code
+- **Syntax Highlighting**: Code snippets are colorized for readability
+- **Source Map Support**: Works with TypeScript and transpiled code
+- **Smart Filtering**: Focuses on your code, not `node_modules`
+- **Zero Runtime Cost**: Only activates when errors are thrown
+- **Graceful Fallback**: Never crashes your app—falls back to standard traces if needed
+
+## Before & After
+
+**Before (Standard Node.js):**
+```
+TypeError: Cannot read properties of undefined (reading 'name')
+    at getUser (/app/src/services/user.ts:45:12)
+    at processRequest (/app/src/handlers/api.ts:23:8)
+    at /app/src/index.ts:67:5
+```
+
+**After (error-less):**
+```
+TypeError: Cannot read properties of undefined (reading 'name')
+   → ./src/services/user.ts:45:12
+
+   43 │ function getUser(id: string) {
+   44 │   const user = users.get(id);
+ > 45 │   return user.name;
+      │               ^^^
+   46 │ }
+   47 │
+
+  tip: Verify the value type matches what the operation expects
+```
+
+## Installation
+
+```bash
+npm install error-less
+```
+
+## Quick Start
+
+### Zero-Config (Recommended)
+
+Just import at the top of your entry file:
+
+```typescript
+import 'error-less/register';
+
+// Your code here...
+throw new Error('Something went wrong!');
+```
+
+### Manual Installation
+
+For more control:
+
+```typescript
+import { install, configure } from 'error-less';
+
+install({
+  showFullStack: true,
+  contextLinesBefore: 3,
+  contextLinesAfter: 3,
+});
+```
+
+### Format Errors in try/catch
+
+```typescript
+import { formatError } from 'error-less';
+
+try {
+  riskyOperation();
+} catch (error) {
+  console.error(formatError(error));
+  // Handle the error...
+}
+```
+
+## Configuration Options
+
+```typescript
+import { install } from 'error-less';
+
+install({
+  // Lines of context before the error line (default: 2)
+  contextLinesBefore: 2,
+
+  // Lines of context after the error line (default: 2)
+  contextLinesAfter: 2,
+
+  // Enable source map resolution (default: true)
+  enableSourceMaps: true,
+
+  // Filter out node_modules frames (default: true)
+  filterNodeModules: true,
+
+  // Show full stack trace after code frame (default: false)
+  showFullStack: false,
+
+  // Force colors on/off (default: auto-detected)
+  colors: true,
+
+  // Custom frame filter
+  frameFilter: (frame) => !frame.filePath.includes('test'),
+});
+```
+
+## API Reference
+
+### Core Functions
+
+#### `install(config?: ErrorLessConfig): void`
+Installs the custom stack trace handler.
+
+#### `uninstall(): void`
+Restores the original stack trace behavior.
+
+#### `configure(config: Partial<ErrorLessConfig>): void`
+Updates configuration without reinstalling.
+
+#### `formatError(error: Error): string`
+Returns a formatted error string. Useful for try/catch blocks.
+
+#### `formatThrown(thrown: unknown): string`
+Formats any thrown value (not just Error instances).
+
+#### `isEnabled(): boolean`
+Returns whether error-less is currently active.
+
+### Utility Functions
+
+#### `getErrorFrames(error: Error): ParsedFrame[]`
+Get parsed stack frames for advanced usage.
+
+#### `clearFileCache(): void`
+Clear the file content cache.
+
+#### `clearSourceMapCache(): void`
+Clear the source map consumer cache.
+
+## TypeScript Support
+
+error-less is written in TypeScript and provides full type definitions.
+
+```typescript
+import type { ErrorLessConfig, ParsedFrame } from 'error-less';
+```
+
+## Source Map Support
+
+error-less automatically detects and uses source maps:
+
+1. **Inline source maps**: Embedded in the compiled file as base64
+2. **External source maps**: `.map` files alongside compiled files
+3. **Embedded source content**: Uses `sourcesContent` from maps when available
+
+For TypeScript, ensure your `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "sourceMap": true
+  }
+}
+```
+
+## How It Works
+
+error-less hooks into V8's `Error.prepareStackTrace` API. When an error's `.stack` property is accessed:
+
+1. The custom handler receives structured stack frame data
+2. Frames are parsed to extract file paths, line numbers, and columns
+3. Source maps are checked for original source locations
+4. Source files are read and code context is extracted
+5. A beautiful, syntax-highlighted output is generated
+
+This approach has **zero performance impact** during normal execution—code only runs when an error is thrown and its stack is accessed.
+
+## Comparison
+
+| Feature | error-less | pretty-error | youch |
+|---------|-----------|--------------|-------|
+| Zero config | ✅ | ❌ | ❌ |
+| Source code display | ✅ | ❌ | ✅ |
+| Source map support | ✅ | ❌ | ✅ |
+| Syntax highlighting | ✅ | ❌ | ❌ |
+| Smart filtering | ✅ | ✅ | ✅ |
+| Pure terminal output | ✅ | ✅ | ❌ (HTML) |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,112 @@
+import { P as ParsedFrame, C as CallSite, a as CodeContext, S as SourceMapResult, E as ErrorLessConfig, i as install } from './register-BG47xgjJ.mjs';
+export { c as configure, d as defaultConfig, f as formatError, b as formatThrown, g as getConfig, e as getErrorFrames, h as isEnabled, u as uninstall } from './register-BG47xgjJ.mjs';
+
+/**
+ * Stack Trace Parser
+ * Extracts structured information from V8 CallSite objects
+ */
+
+/**
+ * Parse a single CallSite into a structured frame
+ */
+declare function parseCallSite(callSite: CallSite): ParsedFrame | null;
+/**
+ * Parse the entire structured stack trace
+ */
+declare function parseStackTrace(structuredStack: CallSite[]): ParsedFrame[];
+/**
+ * Find the first user code frame (the most relevant error location)
+ */
+declare function findUserCodeFrame(frames: ParsedFrame[]): ParsedFrame | null;
+/**
+ * Format a frame as a standard stack trace line
+ */
+declare function formatFrameAsStackLine(frame: ParsedFrame): string;
+/**
+ * Get relative path from current working directory
+ */
+declare function getRelativePath(absolutePath: string): string;
+
+/**
+ * Context Engine - Source File Reader
+ * Reads source files and extracts code context around error locations
+ */
+
+/**
+ * Clear the file cache (useful for long-running processes)
+ */
+declare function clearFileCache(): void;
+/**
+ * Extract code context around a specific line
+ */
+declare function getCodeContext(filePath: string, lineNumber: number, columnNumber: number, linesBefore?: number, linesAfter?: number): CodeContext | null;
+/**
+ * Get code context for a parsed frame, with source map support
+ */
+declare function getContextForFrame(frame: ParsedFrame, sourceMapResult: SourceMapResult | null, linesBefore?: number, linesAfter?: number): CodeContext | null;
+/**
+ * Check if a file exists synchronously
+ */
+declare function fileExists(filePath: string): boolean;
+
+/**
+ * Source Map Support
+ * Resolves compiled code locations back to original source files
+ */
+
+/**
+ * Resolve a frame location through source maps
+ */
+declare function resolveSourceMap(frame: ParsedFrame): SourceMapResult | null;
+/**
+ * Clear the source map cache
+ */
+declare function clearSourceMapCache(): void;
+/**
+ * Preload source-map module (no-op in built-in implementation)
+ */
+declare function preloadSourceMapModule(): Promise<boolean>;
+
+/**
+ * Renderer - Beautiful Terminal Error Output
+ * Creates Rust-style error displays with code frames and syntax highlighting
+ */
+
+/**
+ * Main render function - creates the complete error display
+ */
+declare function renderError(error: Error, topFrame: ParsedFrame | null, codeContext: CodeContext | null, allFrames: ParsedFrame[], sourceMapResult: SourceMapResult | null, config?: Required<ErrorLessConfig>): string;
+/**
+ * Render a minimal error when we can't get context
+ */
+declare function renderMinimalError(error: Error, frames: ParsedFrame[]): string;
+/**
+ * Format an error for use in try/catch blocks
+ * Returns a string that can be logged
+ */
+declare function formatErrorString(error: Error): string;
+
+/**
+ * error-less
+ * Beautiful, Rust-style error reporting for Node.js
+ *
+ * @example
+ * // Auto-install with zero config
+ * import 'error-less/register';
+ *
+ * @example
+ * // Manual installation with options
+ * import { install } from 'error-less';
+ * install({ showFullStack: true });
+ *
+ * @example
+ * // Format errors in try/catch
+ * import { formatError } from 'error-less';
+ * try {
+ *   riskyOperation();
+ * } catch (error) {
+ *   console.error(formatError(error));
+ * }
+ */
+
+export { CallSite, CodeContext, ErrorLessConfig, ParsedFrame, SourceMapResult, clearFileCache, clearSourceMapCache, install as default, fileExists, findUserCodeFrame, formatErrorString, formatFrameAsStackLine, getCodeContext, getContextForFrame, getRelativePath, install, parseCallSite, parseStackTrace, preloadSourceMapModule, renderError, renderMinimalError, resolveSourceMap };

package/dist/index.d.ts

@@ -0,0 +1,112 @@
+import { P as ParsedFrame, C as CallSite, a as CodeContext, S as SourceMapResult, E as ErrorLessConfig, i as install } from './register-BG47xgjJ.js';
+export { c as configure, d as defaultConfig, f as formatError, b as formatThrown, g as getConfig, e as getErrorFrames, h as isEnabled, u as uninstall } from './register-BG47xgjJ.js';
+
+/**
+ * Stack Trace Parser
+ * Extracts structured information from V8 CallSite objects
+ */
+
+/**
+ * Parse a single CallSite into a structured frame
+ */
+declare function parseCallSite(callSite: CallSite): ParsedFrame | null;
+/**
+ * Parse the entire structured stack trace
+ */
+declare function parseStackTrace(structuredStack: CallSite[]): ParsedFrame[];
+/**
+ * Find the first user code frame (the most relevant error location)
+ */
+declare function findUserCodeFrame(frames: ParsedFrame[]): ParsedFrame | null;
+/**
+ * Format a frame as a standard stack trace line
+ */
+declare function formatFrameAsStackLine(frame: ParsedFrame): string;
+/**
+ * Get relative path from current working directory
+ */
+declare function getRelativePath(absolutePath: string): string;
+
+/**
+ * Context Engine - Source File Reader
+ * Reads source files and extracts code context around error locations
+ */
+
+/**
+ * Clear the file cache (useful for long-running processes)
+ */
+declare function clearFileCache(): void;
+/**
+ * Extract code context around a specific line
+ */
+declare function getCodeContext(filePath: string, lineNumber: number, columnNumber: number, linesBefore?: number, linesAfter?: number): CodeContext | null;
+/**
+ * Get code context for a parsed frame, with source map support
+ */
+declare function getContextForFrame(frame: ParsedFrame, sourceMapResult: SourceMapResult | null, linesBefore?: number, linesAfter?: number): CodeContext | null;
+/**
+ * Check if a file exists synchronously
+ */
+declare function fileExists(filePath: string): boolean;
+
+/**
+ * Source Map Support
+ * Resolves compiled code locations back to original source files
+ */
+
+/**
+ * Resolve a frame location through source maps
+ */
+declare function resolveSourceMap(frame: ParsedFrame): SourceMapResult | null;
+/**
+ * Clear the source map cache
+ */
+declare function clearSourceMapCache(): void;
+/**
+ * Preload source-map module (no-op in built-in implementation)
+ */
+declare function preloadSourceMapModule(): Promise<boolean>;
+
+/**
+ * Renderer - Beautiful Terminal Error Output
+ * Creates Rust-style error displays with code frames and syntax highlighting
+ */
+
+/**
+ * Main render function - creates the complete error display
+ */
+declare function renderError(error: Error, topFrame: ParsedFrame | null, codeContext: CodeContext | null, allFrames: ParsedFrame[], sourceMapResult: SourceMapResult | null, config?: Required<ErrorLessConfig>): string;
+/**
+ * Render a minimal error when we can't get context
+ */
+declare function renderMinimalError(error: Error, frames: ParsedFrame[]): string;
+/**
+ * Format an error for use in try/catch blocks
+ * Returns a string that can be logged
+ */
+declare function formatErrorString(error: Error): string;
+
+/**
+ * error-less
+ * Beautiful, Rust-style error reporting for Node.js
+ *
+ * @example
+ * // Auto-install with zero config
+ * import 'error-less/register';
+ *
+ * @example
+ * // Manual installation with options
+ * import { install } from 'error-less';
+ * install({ showFullStack: true });
+ *
+ * @example
+ * // Format errors in try/catch
+ * import { formatError } from 'error-less';
+ * try {
+ *   riskyOperation();
+ * } catch (error) {
+ *   console.error(formatError(error));
+ * }
+ */
+
+export { CallSite, CodeContext, ErrorLessConfig, ParsedFrame, SourceMapResult, clearFileCache, clearSourceMapCache, install as default, fileExists, findUserCodeFrame, formatErrorString, formatFrameAsStackLine, getCodeContext, getContextForFrame, getRelativePath, install, parseCallSite, parseStackTrace, preloadSourceMapModule, renderError, renderMinimalError, resolveSourceMap };