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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
asError
✓ import { asError } from 'catch-unknown';
✗ const asError = require('catch-unknown').asError;
Used to convert any thrown value into an object conforming to the standard Error interface for consistent error handling. The CommonJS `require` syntax is a common pitfall in modern ESM-first environments.
isError
✓ import { isError } from 'catch-unknown';
✗ const isError = require('catch-unknown').isError;
A TypeScript type guard function that asserts whether a value is an instance of the Error interface. Similar to `asError`, be mindful of module import syntax in different environments.
Demonstrates using `asError` within an asynchronous `try...catch` block to safely extract a message from any thrown value (Error, string, object) and log it, then rethrow the original.
import { asError } from 'catch-unknown';
// A dummy logger for demonstration purposes
const logger = {
warn: (message: string) => console.warn(`[WARN] ${message}`),
error: (message: string) => console.error(`[ERROR] ${message}`)
};
async function performRiskyOperation() {
return new Promise((resolve, reject) => {
// Simulate an error or non-Error throw
const rand = Math.random();
if (rand < 0.3) {
reject(new Error('Standard error occurred'));
} else if (rand < 0.6) {
reject('A simple string was thrown');
} else {
reject({ code: 500, detail: 'An unexpected object was thrown' });
}
});
}
async function runExample() {
try {
await performRiskyOperation();
console.log('Operation successful!');
} catch (err) {
// Use asError to safely log the error message regardless of what was thrown
const errorObject = asError(err);
logger.warn(`Operation failed: ${errorObject.message}`);
// Rethrow the original error if necessary
throw err;
}
}
runExample().catch(finalErr => {
logger.error(`Application level error caught: ${asError(finalErr).message}`);
});
Debug
Known issues
gotchaTypeScript versions 4.4 and above default `catch` block variables to `unknown` type when `useUnknownInCatchVariables` is enabled (implicitly by `strict` mode or explicitly). This change means you cannot directly access properties like `.message` or `.name` on a caught `err` without explicit type narrowing or conversion, leading to TypeScript errors.fixIntegrate `catch-unknown` by using `isError(err)` as a type guard (`if (isError(err)) { ... }`) or `asError(err)` to convert the `unknown` value into an `Error`-like object before attempting to access its properties (e.g., `asError(err).message`). affects: TypeScript >=4.4
Errors
Common errors & fixes
Property 'message' does not exist on type 'unknown'.
Attempting to access properties (e.g., `.message`, `.name`) directly on a `catch` variable typed as `unknown` without prior type narrowing or conversion. This is the default behavior for `catch` variables in TypeScript 4.4 and newer when `useUnknownInCatchVariables` is active.
fixUse `catch-unknown`'s `isError` type guard (`if (isError(err)) { ... }`) or convert the error using `asError(err)` before accessing properties (e.g., `asError(err).message`). Ensure your `tsconfig.json` has `useUnknownInCatchVariables` enabled. TypeError: (0, catch_unknown_1.asError) is not a function
This error typically indicates a CommonJS/ESM module interop issue where a named export is incorrectly imported as a default, or a bundler misinterprets the module format when transpiling.
fixEnsure you are using named imports for `asError` and `isError`: `import { asError } from 'catch-unknown';`. If using CommonJS, correctly destructure the named export: `const { asError } = require('catch-unknown');`. Cannot find module 'catch-unknown' or its corresponding type declarations.
The package is not installed in the project, or TypeScript cannot locate its declaration files (`.d.ts`), which are essential for type checking.
fixInstall the package via your package manager: `npm install catch-unknown` or `yarn add catch-unknown`. If the problem persists in a TypeScript project, verify your `tsconfig.json` `types` or `typeRoots` settings, although this is uncommon for well-maintained packages.
Audit
Dependencies
No dependency data recorded yet.