essentials

library1.1.9jsnpmunverified

Essentials is a lightweight JavaScript utility designed for fundamental process initialization, primarily targeting Node.js and other V8-based environments (Chrome, Edge). Its main functions are to ensure that error stack traces include all available stack frames (a common limitation in many JavaScript engines outside of Firefox's hardcoded 128-frame limit) and, crucially, to convert unhandled promise rejections into uncaught exceptions. This prevents silent failures in asynchronous code, making debugging significantly easier. The package is currently at version 1.2.0 (last updated December 2021), indicating a stable project with a low release cadence, focusing on core process hygiene rather than feature expansion. It differentiates itself by providing these essential process-level enhancements with a minimal footprint and simple integration.

observability testing

npm install essentials

github ↗package ↗

INSTALL

IMPORT

SIG · ESSENTIALS

essentials

observabilityjavascriptv1.1.9

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

Side-effect import

✓ require('essentials');

✗ import 'essentials'; // ESM is not the primary usage model

This package is designed for a side-effect CommonJS `require()` at the very top of your main entry file to initialize global error handling behavior. There are no named exports.

Initializes essentials to ensure unhandled promise rejections become uncaught exceptions, demonstrating its core functionality.

/* In your main entry file (e.g., index.js) */ require('essentials'); console.log('Essentials initialized.'); // Demonstrate unhandled rejection becoming an uncaught exception const myPromise = new Promise((resolve, reject) => { setTimeout(() => { reject(new Error('This is an unhandled promise rejection!')); }, 100); }); // In a real application, you might do other setup here. // The script will exit with an uncaught exception after 100ms.

Debug

Known issues

gotchaEssentials primarily targets V8-based engines (Node.js, Chrome, Microsoft Edge). While stack trace adjustments may have some effect elsewhere, the conversion of unhandled promise rejections to uncaught exceptions is specific to V8's behavior. For other engines, relying on Promise polyfills that emit `unhandledrejection` events is recommended for similar functionality.

fix

Ensure you understand the runtime environment. For non-V8 engines, consider a robust Promise polyfill that emits 'unhandledrejection' events for comprehensive error reporting.

affects: >=1.0.0

breakingPrior to v1.2.0, requiring the 'essentials' module multiple times within the same process could lead to silent unhandled rejections, as the error handling mechanisms might be inadvertently overridden or re-initialized incorrectly.

fix

Update to `essentials@1.2.0` or higher to prevent doubled module loads. Ensure `require('essentials')` is called only once at the very top of your main application entry point.

affects: <1.2.0

gotchaThe stack frame adjustment only affects the maximum number of frames reported. Firefox has a hardcoded limit of 128 frames that cannot be adjusted by this package.

fix

Be aware of engine-specific limitations. This feature provides a best-effort improvement for stack traces on adjustable engines, but cannot override browser-specific hard limits.

affects: >=1.0.0

Errors

Common errors & fixes

UnhandledPromiseRejectionWarning: This is an unhandled promise rejection!

The 'essentials' module was not loaded, or was loaded too late in the process lifecycle to capture all rejections.

fix

Ensure `require('essentials');` is the very first line in your main application entry point (e.g., `index.js` or `app.js`).

TypeError: require is not a function (when using import)

Attempting to use `require('essentials')` in an ES module environment (e.g., a file with `type: module` in `package.json` or `.mjs` extension).

fix

While `essentials` is primarily designed for CommonJS, if you must use it in an ES Module context, you might need to use `import {} from 'essentials';` or dynamic import (`import('essentials');`) for its side-effects, though its primary intended usage is with `require` at the root of a CJS application.

Upgrade

Version history

1.1.9latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/medikoo/essentials ↗

packagehttps://www.npmjs.com/package/essentials ↗