{"id":13429,"library":"layerr","title":"Layerr: Error Wrapping Utility","description":"Layerr is a lightweight, dependency-free error wrapping utility for both Node.js and browser environments, designed to enhance error handling in complex applications. Currently at version 3.0.0, it provides a structured way to chain errors, attach arbitrary contextual information, and rename error types dynamically. Layerr is based on the concepts of `VError` but significantly lighter, stripping away Node.js core utility dependencies to ensure better browser compatibility and smaller bundle sizes. It is written in TypeScript and compiled to JavaScript, making it suitable for modern development workflows. The package maintains an active release cadence, focusing on stability and minimal overhead, differentiating itself by its lean design, ESM-only distribution (since v3), and strong TypeScript support for improved developer experience.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/perry-mitchell/layerr","tags":["javascript","error","verror","err","nerror","exception","wrapper","extend","typescript"],"install":[{"cmd":"npm install layerr","lang":"bash","label":"npm"},{"cmd":"yarn add layerr","lang":"bash","label":"yarn"},{"cmd":"pnpm add layerr","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Layerr is an ESM library since v3; CommonJS `require` is not supported for direct import.","wrong":"const { Layerr } = require('layerr')","symbol":"Layerr","correct":"import { Layerr } from 'layerr'"},{"note":"`setGlobalName` is a named export, not a method on the `Layerr` class itself, and should be imported directly.","wrong":"import Layerr from 'layerr'; Layerr.setGlobalName(...)","symbol":"setGlobalName","correct":"import { setGlobalName } from 'layerr'"},{"note":"When only importing the type for TypeScript, use `import type` for better tree-shaking and explicit intent.","symbol":"Layerr (Type)","correct":"import type { Layerr } from 'layerr'"}],"quickstart":{"code":"import { Layerr, setGlobalName } from 'layerr';\n\nasync function simulateTask() {\n  return new Promise((resolve, reject) => {\n    // Simulate an async operation that might fail\n    setTimeout(() => {\n      const shouldFail = Math.random() > 0.5;\n      if (shouldFail) {\n        reject(new Error('Original database error'));\n      } else {\n        resolve('Data fetched successfully');\n      }\n    }, 100);\n  });\n}\n\nasync function runExample() {\n  setGlobalName('MyApplicationError'); // Dynamically change the error name\n  try {\n    await simulateTask();\n    console.log('Task completed without errors!');\n  } catch (originalError) {\n    // Wrap the original error with Layerr, adding context info\n    const wrappedError = new Layerr(\n      {\n        cause: originalError,\n        info: {\n          code: 5001,\n          severity: 'high',\n          userId: 'user-abc-123'\n        }\n      },\n      'Failed to retrieve critical data from the backend.'\n    );\n    console.error(`Caught an error: ${wrappedError.name} [${wrappedError.info.code}]: ${wrappedError.message}`);\n    console.error(`Original cause: ${wrappedError.cause?.message}`);\n    console.error('Additional info:', Layerr.info(wrappedError));\n  }\n}\n\nrunExample();\n","lang":"typescript","description":"This quickstart demonstrates creating and wrapping errors with Layerr, attaching contextual information, and dynamically renaming the error type. It simulates an asynchronous operation that may fail and shows how to catch and re-throw an error using Layerr for enhanced debugging and error reporting."},"warnings":[{"fix":"Update your import statements to use `import { Layerr } from 'layerr'` syntax. Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json` or using `.mjs` file extensions).","message":"Layerr v3 and above is an ECMAScript Module (ESM) library only. Direct `require()` statements for importing `Layerr` will fail.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Instead of `error.info.code`, use `Layerr.info(error).code` for reliable access to attached data.","message":"When accessing information attached to a Layerr instance, always use the static `Layerr.info(error)` method, rather than trying to access an `info` property directly on the error object, as the property might not be directly available or correctly typed.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `setGlobalName` judiciously, preferably at application startup for a consistent error name, or revert it to `null` if temporary changes are needed: `setGlobalName(null)`.","message":"The `setGlobalName` function changes the default `name` property for all *newly created* Layerr instances globally. This can lead to unexpected behavior if not managed carefully in applications with multiple error types or concurrent operations.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { Layerr } = require('layerr')` to `import { Layerr } from 'layerr'`. Ensure your project `package.json` has `\"type\": \"module\"` or use `.mjs` file extensions for ESM files.","cause":"Attempting to import Layerr v3+ using CommonJS `require()` syntax in a non-ESM environment.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ...layerr/dist/index.js from ... not supported."},{"fix":"Use the static method `const { code } = Layerr.info(err);` to correctly retrieve attached information from a Layerr instance.","cause":"Trying to directly access an `info` property on a `Layerr` instance without using the static `Layerr.info()` helper.","error":"Property 'info' does not exist on type 'Layerr'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}