{"id":18030,"library":"custom-error-instance","title":"Custom Error Instance","description":"The `custom-error-instance` library provides a robust mechanism for creating custom JavaScript error constructors that correctly resolve with `instanceof` checks, including support for inheritance hierarchies. It seamlessly integrates with Node.js's native `Error` implementation, allowing developers to extend and define distinct error types without directly modifying the global `Error` object. Key features include the ability to attach custom properties, control error output, and specify stack trace lengths, addressing common challenges when creating custom error classes. The package is currently at version 2.1.2 (as of late 2023) and appears to be in a maintenance phase, with updates occurring on an as-needed basis rather than a fixed release cadence. Its primary differentiator lies in ensuring reliable `instanceof` behavior for custom errors, which can be tricky to implement correctly when extending the native `Error` class manually.","status":"maintenance","version":"2.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/Gi60s/custom-error-instance","tags":["javascript","error","custom","custom-error","instance","instanceof"],"install":[{"cmd":"npm install custom-error-instance","lang":"bash","label":"npm"},{"cmd":"yarn add custom-error-instance","lang":"bash","label":"yarn"},{"cmd":"pnpm add custom-error-instance","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is primarily a CommonJS module.","symbol":"CustomError","correct":"const CustomError = require('custom-error-instance');"},{"note":"When used in an ESM context, Node.js's interoperability allows `import CustomError from 'pkg'` for a CommonJS module's `module.exports`. A named import will typically fail.","wrong":"import { CustomError } from 'custom-error-instance';","symbol":"CustomError","correct":"import CustomError from 'custom-error-instance';"},{"note":"Custom errors are created by calling the `CustomError` function, not by extending it as a class directly. This function returns a constructor.","wrong":"class Child extends CustomError {}","symbol":"ChildErrorClass","correct":"const Child = CustomError('ChildError', Parent);"}],"quickstart":{"code":"const CustomError = require('custom-error-instance');\n\nconst store = {};\n\n// Define a base custom error\nconst MapError = CustomError('MapError');\n\n// Define a child error for 'key in use' inheriting from MapError\nMapError.inuse = CustomError(MapError, {\n  message: 'The specified key is already in use.',\n  code: 'INUSE'\n});\n\n// Define another child error for 'invalid value'\nMapError.invalidValue = CustomError(MapError, {\n  message: 'The provided value is invalid.',\n  code: 'INVALID_VALUE'\n});\n\nfunction add(key, value) {\n  if (typeof value !== 'number' && typeof value !== 'string') {\n    throw new MapError.invalidValue(`Invalid value type for key '${key}'.`);\n  }\n  if (Math.random() < 0.3) {\n    throw new MapError(`Random transient error during add operation for key '${key}'.`);\n  }\n  if (store.hasOwnProperty(key)) {\n    throw new MapError.inuse(`Key '${key}' is already in use.`);\n  }\n  store[key] = value;\n  console.log(`Added key '${key}' with value '${value}'.`);\n}\n\ntry {\n  add('user_id', 123);\n  add('username', 'Alice');\n  add('user_id', 456); // This will throw MapError.inuse\n} catch (e) {\n  if (e instanceof MapError.inuse) {\n    console.error(`Caught INUSE error: ${e.message} (Code: ${e.code})`);\n  } else if (e instanceof MapError.invalidValue) {\n    console.error(`Caught INVALID_VALUE error: ${e.message} (Code: ${e.code})`);\n  } else if (e instanceof MapError) {\n    console.error(`Caught generic MapError: ${e.message}`);\n  } else {\n    console.error(`Caught unexpected error: ${e.message}`);\n    throw e;\n  }\n}\nconsole.log('Store state:', store);\n","lang":"javascript","description":"This example demonstrates how to define a base custom error, create inheriting child errors with specific properties (like a 'code'), and use `instanceof` checks to handle different error types within a `try...catch` block. It simulates adding items to a store with potential key conflicts or random errors."},"warnings":[{"fix":"For explicit CJS usage, stick to `require`. For ESM, `import CustomError from 'custom-error-instance';` is generally the correct approach for default exports from CJS. Avoid named imports like `import { CustomError } from 'custom-error-instance';` as they are unlikely to work.","message":"The `custom-error-instance` package is primarily distributed as a CommonJS module. While Node.js's ESM interoperability often allows `import CustomError from 'custom-error-instance';`, developers should be aware of potential CJS/ESM impedance mismatches in complex build environments or with older Node.js versions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review the project's specific needs regarding new JS features or comprehensive TS types. For the core functionality of custom `instanceof` errors, it remains effective. Consider contributing typings if needed for TypeScript projects.","message":"The package's latest release (v2.1.2) was in late 2023, and updates are not frequent. While stable, it may not leverage the absolute latest JavaScript features or provide extensive TypeScript typings, which could be a consideration for projects heavily reliant on modern language features or strict TypeScript definitions.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Ensure `CustomError` is imported correctly for CommonJS: `const CustomError = require('custom-error-instance');` or for ESM interoperability: `import CustomError from 'custom-error-instance';`.","cause":"Attempting to use `CustomError` as a function or constructor when it was imported incorrectly, often due to using a named import `import { CustomError } from 'custom-error-instance';` on a CommonJS default export.","error":"TypeError: CustomError is not a function"},{"fix":"Verify that `CustomError` itself is correctly imported and that sub-errors like `CustomError.inuse` have been properly defined using `CustomError('ChildError', ParentError, ...)` before instantiation.","cause":"This error can occur if you try to `new` up a property on the `CustomError` object without first defining `CustomError` correctly, or if you're trying to access a nested error type (e.g., `inuse`) from an incorrectly imported top-level `CustomError` object.","error":"TypeError: customErrorInstance.inuse is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}