Registry / observability / youch-core

youch-core

JSON →
library0.3.3jsnpmunverified

youch-core is a specialized JavaScript/TypeScript library designed to parse `Error` instances into a structured collection of detailed stack frames. It functions as the core error parsing engine utilized by the `youch` package, which is responsible for rendering user-friendly error pages in web applications and formatted output in terminal environments. This library is considered low-level, intended for developers who need to build custom error display solutions while leveraging `youch-core`'s robust error introspection capabilities, rather than being a direct-use package for most applications. It provides granular information for each stack frame, including the filename, line number, column number, and a snippet of the relevant source code, along with flags indicating if a frame is related to `node_modules` or is a native function. The current stable version is `0.3.3`, reflecting an active development cadence with several minor releases and dependency updates throughout the past year, indicating ongoing maintenance and improvement. A significant feature is its support for custom source code loaders, enabling integration into diverse JavaScript runtime environments like Deno or Bun where standard Node.js `fs` module access might be unavailable or unsuitable for retrieving source files. It explicitly targets and supports modern Node.js versions (v18 and newer) and includes comprehensive TypeScript type definitions, ensuring a smooth and type-safe development experience for TypeScript users building custom error handling utilities.

npm install youch-core
INSTALL
IMPORT
SIG · YOUCH-CORE
Y
youch-core
observabilityjavascriptv0.3.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ErrorParser
import { ErrorParser } from 'youch-core'
const ErrorParser = require('youch-core').ErrorParser
The library is primarily designed for ES Modules. Use named imports.
ParsedError
import { ParsedError } from 'youch-core'
This type definition is useful for type-checking the result of `parser.parse()`.
StackFrame
import { StackFrame } from 'youch-core'
This type defines the structure of individual stack frames, commonly used when iterating `parsedError.frames` or implementing a custom source loader.

Demonstrates parsing a JavaScript error into structured stack frames, including mocking a custom source loader for illustrative purposes and logging key frame details.

import { ErrorParser, ParsedError, StackFrame } from 'youch-core'; async function main() { const error = new Error('Failed to process user input'); // Simulating a more complex stack for demonstration error.stack = `Error: Failed to process user input\n at validateInput (file:///path/to/project/src/utils/validation.ts:15:20)\n at processRequest (file:///path/to/project/src/handlers/apiHandler.ts:30:10)\n at Router.dispatch (node:internal/deps/undici/undici.js:123:45)\n at Server.<anonymous> (file:///path/to/project/src/server.ts:8:5)`; const parser = new ErrorParser(); // Optionally, define a custom source loader if files are not on disk parser.defineSourceLoader(async (frame: StackFrame) => { if (frame.fileName && frame.type === 'file') { // In a real application, you might fetch source code from a build artifact, // a CDN, or an in-memory map. // For this example, we'll just mock a source line. if (frame.fileName.includes('validation.ts')) { frame.source = [' ', ' function validateInput(data: any) {', ' if (!data.isValid) { throw new Error("Invalid data"); }', ' }']; } else if (frame.fileName.includes('apiHandler.ts')) { frame.source = [' ', ' async function processRequest(req: Request) {', ' await validateInput(req.body);', ' }']; } } }); const parsedError: ParsedError = await parser.parse(error); console.log(`Error Message: ${parsedError.message}`); console.log(`Original Stack: ${parsedError.error.stack?.split('\n')[0]}...`); console.log(`Total Frames: ${parsedError.frames.length}\n`); console.log('--- Key Stack Frames ---'); // Iterate over application-specific frames, excluding node_modules and native calls parsedError.frames .filter(f => !f.isNodeModule && !f.isNative) .slice(0, 5) // Show top 5 relevant frames .forEach((frame, index) => { console.log(`Frame ${index + 1}:`); console.log(` Method: ${frame.method || '[anonymous]'}`); console.log(` File: ${frame.fileName || '[unknown file]'}:${frame.lineNumber || '?'}`); if (frame.source && frame.source.length > 0) { const lineIndex = (frame.lineNumber ?? 1) - 1; const sourceLine = frame.source[lineIndex]?.trim(); console.log(` Code: ${sourceLine || '[Source unavailable]'}`); } else { console.log(' Code: [Source not loaded]'); } console.log(''); }); } main().catch(console.error);
Debug
Known issues
breakingThe `error.metadata` property was removed from the parsed error object.
fix
Remove any references to `error.metadata`. This property is now managed by the higher-level `youch` package for HTML rendering and is no longer part of `youch-core`'s output.
affects: >=0.2.3
breakingThe signature for the custom source loader defined via `parser.defineSourceLoader` changed.
fix
Update existing custom source loaders. The `defineSourceLoader` method now expects a callback that accepts a `StackFrame` object as its sole argument, providing more contextual information. Refer to the current documentation or TypeScript types for the updated signature.
affects: >=0.2.5
gotchaVersions `0.3.2` and above explicitly require Node.js 18 or newer.
fix
Ensure your Node.js runtime environment is version 18 or later. Running `youch-core` on older Node.js versions may lead to compatibility issues or errors related to unsupported syntax or APIs.
affects: >=0.3.2
Errors
Common errors & fixes
TypeError: ErrorParser is not a constructor
Attempting to use `require()` to import `ErrorParser` in a CommonJS environment, while `youch-core` is primarily distributed as an ES Module.
fix
Use ES module import syntax: `import { ErrorParser } from 'youch-core'`. Ensure your project is configured for ES Modules (e.g., by adding `"type": "module"` to your `package.json` or using `.mjs` file extensions).
TypeError: Cannot read properties of undefined (reading 'frames')
The `ErrorParser.parse()` method is asynchronous and returns a Promise. This error typically occurs if you forget to `await` its result.
fix
Always use `await` when calling `parser.parse(error)`. For example: `const parsedError = await parser.parse(error)` within an `async` function.
Property 'source' does not exist on type 'StackFrame'.
Accessing the `source` property on a `StackFrame` without ensuring it's available. The `source` property might be `undefined` if the source code could not be loaded (e.g., for native frames, or if a custom loader failed/wasn't provided).
fix
Check if `frame.source` exists before accessing it (`if (frame.source) { ... }`). Also, ensure your custom `defineSourceLoader` implementation correctly populates the `frame.source` array for relevant frames.
Upgrade
Version history
0.3.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
41 hits · last 30 days
node
34
OpenAI (training)
1
Resources
youch-core — npm install youch-core · libregistry