{"id":14517,"library":"custom-exception","title":"Node Custom Exception Utility","description":"The `custom-exception` package, currently at version 0.1.2, provides a foundational utility for creating custom error classes within Node.js applications. It aims to simplify the process of defining structured, extensible error types beyond the standard JavaScript `Error` object. While still in early development, as indicated by its low version number, it offers a mechanism to differentiate application-specific errors programmatically. Its release cadence is likely irregular, given its nascent stage. Key differentiators typically include boilerplate reduction for custom error inheritance, properties like status codes, and improved stack trace handling, though specifics depend on the full API. Users should anticipate potential API changes as the library evolves towards a stable major release.","status":"active","version":"0.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/Terran-Source/node-custom-exception","tags":["javascript","nodejs","custom-exception"],"install":[{"cmd":"npm install custom-exception","lang":"bash","label":"npm"},{"cmd":"yarn add custom-exception","lang":"bash","label":"yarn"},{"cmd":"pnpm add custom-exception","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily targets modern JavaScript environments. While CommonJS might work via transpilation, direct ESM import is recommended. The API is considered experimental in v0.1.2.","wrong":"const { CustomError } = require('custom-exception');","symbol":"CustomError","correct":"import { CustomError } from 'custom-exception';"},{"note":"To leverage the library's features, extend the provided `CustomError` class instead of the native `Error`.","wrong":"class MyError extends Error { /* ... */ } // Misses custom-exception's features","symbol":"CustomError","correct":"class MyError extends CustomError { /* ... */ }"}],"quickstart":{"code":"import { CustomError } from 'custom-exception';\n\n/**\n * Define a custom application-specific error by extending CustomError.\n * This allows for adding custom properties like 'code' or 'data'.\n */\nclass NotFoundError extends CustomError {\n  constructor(message: string, resourceId?: string) {\n    super(message);\n    this.name = 'NotFoundError';\n    this.statusCode = 404; // Custom property\n    this.resourceId = resourceId; // Custom property\n    // Restore prototype chain for 'instanceof' checks in transpiled environments\n    Object.setPrototypeOf(this, NotFoundError.prototype);\n  }\n}\n\n/**\n * A function that might throw our custom error.\n */\nfunction getUser(userId: string) {\n  if (userId === 'nonexistent') {\n    throw new NotFoundError(`User with ID '${userId}' not found.`, userId);\n  }\n  return { id: userId, name: `User ${userId}` };\n}\n\ntry {\n  const user = getUser('nonexistent');\n  console.log(user);\n} catch (error) {\n  if (error instanceof NotFoundError) {\n    console.error(`Error: ${error.name} - ${error.message} (Status: ${error.statusCode}, Resource: ${error.resourceId})`);\n  } else if (error instanceof CustomError) {\n    console.error(`Caught a generic CustomError: ${error.name} - ${error.message}`);\n  } else if (error instanceof Error) {\n    console.error(`Caught a standard Error: ${error.name} - ${error.message}`);\n  }\n}","lang":"typescript","description":"Demonstrates defining a custom error by extending `CustomError`, adding custom properties, and catching it with `instanceof` checks."},"warnings":[{"fix":"Pin your package version (e.g., `\"custom-exception\": \"0.1.2\"`) and manually review the changelog before upgrading to new minor or patch versions.","message":"As the package is at version 0.1.2, its API is considered unstable. Minor or patch releases may introduce breaking changes without prior deprecation warnings. Users should lock package versions and review changes upon upgrade.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Add `Object.setPrototypeOf(this, MyCustomError.prototype);` to your custom error class constructor after `super(message);`.","message":"When extending `CustomError` in a transpiled environment (e.g., Babel, TypeScript targeting ES5/ES2015), you must explicitly call `Object.setPrototypeOf(this, MyCustomError.prototype)` in the constructor after `super()` to ensure `instanceof` checks work correctly.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always set `this.name = 'MyCustomError';` in the constructor of your derived error class to ensure accurate error identification.","message":"Forgetting to set `this.name` in your custom error class constructor will result in the error name defaulting to 'CustomError' or 'Error' instead of your specific class name.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Always create instances of `CustomError` or its derivatives using `new`, e.g., `throw new CustomError('message');`.","cause":"Attempting to call `CustomError` or a derived class as a function instead of instantiating it with `new`.","error":"TypeError: Class constructor CustomError cannot be invoked without 'new'"},{"fix":"Ensure `Object.setPrototypeOf(this, MyCustomError.prototype);` is called in your custom error's constructor after `super()`.","cause":"This typically occurs in transpiled environments where the prototype chain is not correctly re-established for custom error classes, preventing `instanceof` from working as expected.","error":"MyCustomError is not an instance of CustomError"}],"ecosystem":"npm"}